Headless Kit v0.2.2
DISCLAIMER: This component is in
Beta
status. That means that it is ready for production, but the API might change.

Accordion

A stacked set of interactive headings which reveal or hide their associated content.

Qwik UI's Accordion implementation follows the WAI-Aria design pattern, along with some additional API's that enhance the flexibility, types, and performance.

Building blocks

🎨 Anatomy

ComponentDescription
AccordionRoot

The root container for the accordion.

AccordionItem

An item inside of the root. It contains the item's heading, trigger, and content.

AccordionHeader

An HTML Heading Element. The default is set to h3, can be changed with the as prop.

AccordionTrigger

Toggles the corresponding content when clicked or activated. It should be placed within the AccordionHeader component.

AccordionContent

Contains the content associated with an item when clicking on its respective trigger.

Multiple items

Animations

The previous two examples make use of the animated prop. This prop allows you to use the transition and animation properties without the content immediately closing. In the future, there will be native browser support for transitioning display.

If you're curious about how the accordion is animated, you can use a built-in Qwik UI variable called --qwikui-accordion-content-height.

The variable calculates the content height behind the scenes, so that you can use this variable in your keyframes. Out of the box, you can use the accordion-open and accordion-close keyframes in your project. These use an animation declaration on the height property.

Non-collapsible

By default, the collapsible prop is set to true. You can revert this behavior by setting it to false in the Accordion Root component.

Disabled

When disabling an accordion trigger, you're adding the default disabled browser behavior, along with removing the element from the focus order.

Any disabled elements will be skipped over when using tab or the Up Arrow and Down Arrow keys. You can do this by adding the disabled prop on any trigger.

Default Value

You can open me by default by putting the defaultValue prop on the Accordion Item.

You can make the accordion items uncontrolled by adding the defaultValue prop on the items. This will open an accordion item without user interaction, and can be used on both type single and multi accordions.

Custom Heading Label

By default, when using the AccordionHeader component, it's rendered as an h3 tag. You can render your heading of choice by using the as prop.

Selected Index

Selected Index: X

onSelectedIndexChange$ will keep track of the current selected index. It can be useful for when you want to programmatically change something based on a user's interaction.

Focused Index

Focused Index: X

onFocusIndexChange$ will keep track of the current focused index. It can be useful for when you want to programmatically change something based on what the user focuses.

Dynamic

You can embrace reactivity, using signals, stores, and however else you'd like to use the Accordion with dynamic behavior.

When an Accordion Item is removed, a Visible Task runs that will clean up the DOM node in the browser, ensuring that you stay clear of race condition or memory leak issues.

If you'd prefer to add your own id to the Accordion Item with dynamic behavior, you can add the id prop to the Accordion Item. This can be useful when you'd like the id value to be sync with your custom logic.

By default, the Accordion Item has a locally scoped id with Qwik's useId hook. All children elements will be prefixed by its respective item id, followed by a dash and the element. For example, {id}-trigger.

Accessibility

Keyboard interaction

Key

Description

Tab
Moves focus to the next focusable trigger.
Shift + Tab
Moves focus to the previous focusable trigger.
Space / Enter
Expand or collapse the Accordion Trigger.
Up Arrow
When focus is on an accordion trigger, it will move to the previous one, or the last if at the top.
Down Arrow
When focus is on an accordion trigger, it will move to the next one, or the first if at the bottom.
Home
When on an Accordion Trigger, Moves focus to the first Accordion Trigger.
End
When on an Accordion Trigger, Moves focus to the last Accordion Trigger.

API

Accordion Root

PropTypeDescription
behavior
string

Determines whether the Accordion will open one or multiple items at a time.

collapsible
boolean

Will allow the accordion to collapse items if set to true.

animated
boolean

Allows the trigger to close using the onAnimationEnd$ and onTransitionEnd$ event handlers.

onSelectedIndexChange$
function

An event hook that gets notified whenever the selected index changes.

onFocusIndexChange$
function

An event hook that gets notified whenever the focus index changes.

Accordion Item

PropTypeDescription
id
string

Allows the consumer to supply their own id attribute for the item and its descendants.

defaultValue
boolean

Determines whether the Accordion Item will open by default.

Accordion Header

PropTypeDescription
as
union

Sets the heading tag of the Accordion Header (Rendered HTML)

Common Built-in Props

Thanks to QwikIntrinsicAttributes , you can use most if not all normal JSX props and handlers on the semantically correlated component. Here are some of the most common ones:

PropTypeDescription
class
string

CSS classes you can apply

style
string

CSS styles you can apply

disabled
boolean

Disables the element

onClick$
function

A custom click handler that executes when the element is clicked.

onKeyDown$
function

A custom click handler that executes when the key is pressed down.

onFocus$
function

A custom click handler that executes when element is focused.