Accordion

Use accordions to organize related content in expandable sections. Explore examples with headings, borders, and multiple open panels.

This component requires the following JavaScript plugin:

Accordion

Examples

Default

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px

Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof; or abridging the freedom of speech, or of the press; or the right of the people peaceably to assemble, and to petition the Government for a redress of grievances.

A well regulated Militia, being necessary to the security of a free State, the right of the people to keep and bear Arms, shall not be infringed.

No Soldier shall, in time of peace be quartered in any house, without the consent of the Owner, nor in time of war, but in a manner to be prescribed by law.

HTML

<div
  data-scope="accordion" data-part="root"
  class="space-y-2"
>
  <div
    data-scope="accordion" data-part="item"
    data-value="one"
  >
    <button
      data-scope="accordion" data-part="item-trigger"
      class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
    >
      First Amendment
      <div class="h-full flex items-center ml-auto shrink-0">
        <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
      </div>
    </button>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden"
    >
      <p class="leading-normal max-w-prose">
        Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof;
        or abridging the freedom of speech, or of the press; or the right of the people peaceably to assemble, and to petition the
        Government for a redress of grievances.
      </p>
    </div>
  </div>
  <div
    data-scope="accordion" data-part="item"
    data-value="two"
  >
    <button
      data-scope="accordion" data-part="item-trigger"
      class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
    >
      Second Amendment
      <div class="h-full flex items-center ml-auto shrink-0">
        <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
      </div>
    </button>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden"
    >
      <p class="leading-normal max-w-prose">
        A well regulated Militia, being necessary to the security of a free State, the right of the people to keep and
        bear Arms, shall not be infringed.
      </p>
    </div>
  </div>
  <div
    data-scope="accordion" data-part="item"
    data-value="third"
  >
    <button
      data-scope="accordion" data-part="item-trigger"
      class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
    >
      Third Amendment
      <div class="h-full flex items-center ml-auto shrink-0">
        <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
      </div>
    </button>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden"
    >
      <p class="leading-normal max-w-prose">
        No Soldier shall, in time of peace be quartered in any house, without the consent of the Owner, nor in time of
        war, but in a manner to be prescribed by law.
      </p>
    </div>
  </div>
</div>

With headings

Wrap each trigger in a heading when its panel represents a section of the page. Choose the heading level to fit the page structure, following the WAI-ARIA accordion pattern.

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px

HTML

<div
  data-scope="accordion" data-part="root"
  class="space-y-2"
>
  <div
    data-scope="accordion" data-part="item"
    data-value="one"
  >
    <h4>
      <button
        data-scope="accordion" data-part="item-trigger"
        class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
      >
        First Amendment
        <div class="h-full flex items-center ml-auto shrink-0">
          <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
        </div>
      </button>
    </h4>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden"
    >
      <p class="leading-normal max-w-prose">
        Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof;
        or abridging the freedom of speech, or of the press; or the right of the people peaceably to assemble, and to petition the
        Government for a redress of grievances.
      </p>
    </div>
  </div>
</div>

Multiselectable

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px

A well regulated Militia, being necessary to the security of a free State, the right of the people to keep and bear Arms, shall not be infringed.

No Soldier shall, in time of peace be quartered in any house, without the consent of the Owner, nor in time of war, but in a manner to be prescribed by law.

HTML

<div
  data-scope="accordion" data-part="root"
  data-multiple
  class="space-y-2"
>
  <div
    data-scope="accordion" data-part="item"
    data-value="one"
  >
    <button
      data-scope="accordion" data-part="item-trigger"
      class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
    >
      First Amendment
      <div class="h-full flex items-center ml-auto shrink-0">
        <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
      </div>
    </button>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden"
    >
      <p class="leading-normal max-w-prose">
        Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof;
        or
        abridging the freedom of speech, or of the press; or the right of the people peaceably to assemble, and to
        petition the
        Government for a redress of grievances.
      </p>
    </div>
  </div>
  <div
    data-scope="accordion" data-part="item"
    data-value="two"
  >
    <button
      data-scope="accordion" data-part="item-trigger"
      class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
    >
      Second Amendment
      <div class="h-full flex items-center ml-auto shrink-0">
        <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
      </div>
    </button>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden"
    >
      <p class="leading-normal max-w-prose">
        A well regulated Militia, being necessary to the security of a free State, the right of the people to keep and
        bear Arms, shall not be infringed.
      </p>
    </div>
  </div>
  <div
    data-scope="accordion" data-part="item"
    data-value="third"
  >
    <button
      data-scope="accordion" data-part="item-trigger"
      class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
    >
      Third Amendment
      <div class="h-full flex items-center ml-auto shrink-0">
        <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
      </div>
    </button>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden"
    >
      <p class="leading-normal max-w-prose">
        No Soldier shall, in time of peace be quartered in any house, without the consent of the Owner, nor in time of
        war, but in a manner to be prescribed by law.
      </p>
    </div>
  </div>
</div>

Bordered

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px

A well regulated Militia, being necessary to the security of a free State, the right of the people to keep and bear Arms, shall not be infringed.

No Soldier shall, in time of peace be quartered in any house, without the consent of the Owner, nor in time of war, but in a manner to be prescribed by law.

HTML

<div
  data-scope="accordion" data-part="root"
  class="space-y-2"
>
  <div
    data-scope="accordion" data-part="item"
    data-value="one"
  >
    <button
      data-scope="accordion" data-part="item-trigger"
      class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
    >
      First Amendment
      <div class="h-full flex items-center ml-auto shrink-0">
        <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
      </div>
    </button>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden border-b-4 border-x-4 border-gray-5"
    >
      <p class="leading-normal max-w-prose">
        Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof;
        or
        abridging the freedom of speech, or of the press; or the right of the people peaceably to assemble, and to
        petition the
        Government for a redress of grievances.
      </p>
    </div>
  </div>
  <div
    data-scope="accordion" data-part="item"
    data-value="two"
  >
    <button
      data-scope="accordion" data-part="item-trigger"
      class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
    >
      Second Amendment
      <div class="h-full flex items-center ml-auto shrink-0">
        <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
      </div>
    </button>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden border-b-4 border-x-4 border-gray-5"
    >
      <p class="leading-normal max-w-prose">
        A well regulated Militia, being necessary to the security of a free State, the right of the people to keep and
        bear Arms, shall not be infringed.
      </p>
    </div>
  </div>
  <div
    data-scope="accordion" data-part="item"
    data-value="third"
  >
    <button
      data-scope="accordion" data-part="item-trigger"
      class="group flex items-center w-full py-4 px-5 bg-gray-5 hover:bg-gray-10 font-bold focus:outline-4 focus:outline-blue-40v cursor-pointer text-left gap-3"
    >
      Third Amendment
      <div class="h-full flex items-center ml-auto shrink-0">
        <div class="size-6 icon-[material-symbols--add] group-aria-expanded:icon-[material-symbols--remove]"></div>
      </div>
    </button>
    <div
      data-scope="accordion" data-part="item-content"
      class="py-6 px-4 not-[[data-state=open]]:hidden border-b-4 border-x-4 border-gray-5"
    >
      <p class="leading-normal max-w-prose">
        No Soldier shall, in time of peace be quartered in any house, without the consent of the Owner, nor in time of
        war, but in a manner to be prescribed by law.
      </p>
    </div>
  </div>
</div>

Component API

Initialization

Run once after the accordion markup exists:

import { accordionInit } from '@uswds-tailwind/compat/accordion'

accordionInit()

For an instance you can control, use Accordion.getOrCreateInstance(root, options). See shared instance methods.

Anatomy

Set authored attributes in your HTML. The component manages generated attributes. Types describe HTML attribute values.

`root`

Groups the accordion items.

Attribute	Type	Description
`data-scope`	`"accordion"`	Authored. Identifies the component scope.
`data-part`	`"root"`	Authored. Identifies this part.
`data-multiple`	`boolean-like attribute`	Authored. Allows several open panels. Bare attribute is true; omission or `"false"` is false. Overrides the `multiple` option, even when omitted.

`item`

One panel, containing its trigger and content.

Attribute	Type	Description
`data-part`	`"item"`	Authored. Identifies this part.
`data-value`	`string`	Authored. Required unique, nonempty item value; `id` is used as a fallback.
`data-state`	`"open" \| "closed"`	Authored. Use `"open"` to expand initially. In single-open mode, only the first marked item is used. `defaultValue` overrides these markers.
`data-state`	`"open" \| "closed"`	Generated. `"open"` or `"closed"`; use for styling.

`item-trigger`

Toggles its panel. Place inside a heading when introducing a section.

Attribute	Type	Description
`data-part`	`"item-trigger"`	Authored. Identifies this part.
`data-state`	`"open" \| "closed"`	Generated. `"open"` or `"closed"`; use for styling.
`aria-expanded`	`"true" \| "false"`	Generated. Whether the content is expanded.
`aria-controls`	`ID reference`	Generated. ID of the associated content.

`item-content`

Panel content, inside the same item as its trigger.

Attribute	Type	Description
`data-part`	`"item-content"`	Authored. Identifies this part.
`data-state`	`"open" \| "closed"`	Generated. `"open"` or `"closed"`; use for styling.
`hidden`	`boolean attribute`	Generated. Present when closed.

Configuration

Pass these JavaScript options to the instance constructor or factory. Authored configuration attributes are read during construction.

Option	Description
`defaultValue`	`string[]`. Initial expanded item values; overrides item state markers.
`value`	`string[]`. Controlled expanded values; takes precedence over `defaultValue`.
`id`	Instance identifier; defaults to the root ID or a generated value.
`ids`	Override the `root` ID, or pass `itemTrigger(value)` and `itemContent(value)` functions to generate item IDs.

Methods

Method	Returns	Description
`open(value)`	`Promise<void>`	Requests expansion of the item.
`close(value)`	`Promise<void>`	Requests collapse of the item.
`toggle(value)`	`Promise<void>`	Requests the opposite expanded state.
`destroy()`	`void`	Stops the instance and removes its lookup. Does not restore the original HTML.

import { Accordion } from '@uswds-tailwind/compat/accordion'

const accordion = Accordion.getOrCreateInstance(
  '[data-scope="accordion"][data-part="root"]',
)

await accordion.open('one')

Pass the item’s data-value (or fallback id) as the value argument. Promises settle the queued update, not CSS transitions. When using controlled state, your application must supply the updated value.

See initialization and cleanup.

Callbacks

Callback	Payload	When it runs
`onValueChange`	`{ value: string[] }`	Expanded values change, or a controlled change is requested.

Pass callbacks in instance options. They are JavaScript functions, not emitted DOM events.

Accessibility

Supply meaningful button text and appropriate heading levels.
Enter and Space activate the focused button.