Accordion

A vertically stacked set of collapsible sections that allows users to expand and collapse content panels.

Features

• ✅ Smooth collapse/expand animations
• ✅ Accessible ARIA attributes and roles
• ✅ Full keyboard navigation (Arrow keys, Home, End)
• ✅ Single or multiple items expanded

Installation

import Alpine from 'alpinejs'
import accordion from 'alpine-headless-ui/accordion'

Alpine.plugin(accordion)
Alpine.start()

Examples

Basic Accordion

Alpine Headless UI provides unstyled, accessible UI primitives for Alpine.js applications.

It provides behavior and accessibility while you control the styling and markup structure.

Yes, it's open source and free to use under the MIT license.

With Icon Indicator

Absolutely! The components are completely unstyled, so you have full control over the appearance.

Yes, it works perfectly with Tailwind CSS, plain CSS, or any styling solution.

Multiple Items Open

This accordion allows multiple items to be open at the same time.

Both sections can be expanded simultaneously.

Try expanding all three!

Non-Collapsible

When collapsible is false, at least one item must always be open.

You can't collapse all items when collapsible is false.

API Reference

Component Props

Prop	Type	Default	Description
value	string[]	[]	Array of open item IDs
multiple	boolean	false	Allow multiple items to be open
collapsible	boolean	true	Allow all items to be closed
disabled	boolean	false	Disable all accordion items

Parts

Part	Description
x-accordion:item="id"	Accordion item container with unique ID
x-accordion:item-header	Heading wrapper around the trigger (sets role="heading")
x-accordion:item-trigger	Button that toggles the item
x-accordion:item-content	Content that is shown/hidden
x-accordion:item-indicator	Optional visual indicator element

Data Attributes

Attribute	Description
data-scope	Always set to accordion
data-part	Identifies the part (root, item, item-header, item-trigger, item-content, item-indicator)
data-state	Current state (open or closed)
data-disabled	Present when disabled

Events

Event	Detail	Description
change	{ value: string[] }	Fired when the open items change
focus-change	{ value: string | null }	Fired when the focused item changes

Keyboard Interactions

Key	Action
ArrowDown	Move focus to next item trigger
ArrowUp	Move focus to previous item trigger
Home	Move focus to first item trigger
End	Move focus to last item trigger

Accessing State

You can access the accordion API using $accordion:

<div x-accordion>
  <div x-data>
    <p x-text="'Open items: ' + $accordion.value.length"></p>
  </div>

  <div x-accordion:item="'item-1'">
    <!-- Item content -->
  </div>
</div>

Available properties:

• value - Array of open item IDs
• multiple - Whether multiple items can be open
• collapsible - Whether all items can be closed
• disabled - Whether accordion is disabled
• focusedValue - ID of currently focused item
• isOpen(id) - Check if item is open
• toggle(id) - Toggle an item
• setValue(value) - Set open items programmatically

Accessibility

ARIA Attributes

The accordion automatically includes:

• type="button" on triggers
• aria-expanded on triggers (true/false)
• aria-controls on triggers pointing to the content panel id
• role="region" on content panels
• aria-labelledby on content panels pointing to the trigger id
• role="heading" on x-accordion:item-header
• Proper data attributes for state

Heading Level

The WAI-ARIA accordion pattern requires each trigger to be inside a heading element. Wrap each trigger with x-accordion:item-header on a native heading (<h2>, <h3>, etc.) at the level appropriate for your page's document outline. If you use a non-heading element, provide an explicit aria-level:

<div x-accordion:item-header aria-level="3">
  <button x-accordion:item-trigger>...</button>
</div>

Keyboard Support

Key	Action
Space / Enter	Toggle focused accordion item
ArrowDown	Move focus to next trigger
ArrowUp	Move focus to previous trigger
Home	Move focus to first trigger
End	Move focus to last trigger

See Also

• Collapsible - Single collapsible section
• Tabs - Alternative pattern for showing/hiding content