Search docs

Accordion

A stack of headings that each show or hide a section of content.

Accordion follows the Accordion WAI-ARIA design pattern.

import { component$, useStyles$ } from '@builder.io/qwik';
import { Accordion } from '@leve-ui/accordion';
import { LuChevronDown } from '@qwikest/icons/lucide';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <Accordion.Root class="accordion-default-root">
      <Accordion.Item value="item-1" class="accordion-default-item">
        <Accordion.Header class="accordion-default-header">
          <Accordion.Trigger class="accordion-default-trigger">
            <span>What is leve-ui?</span>
            <LuChevronDown class="accordion-default-chevron" aria-hidden="true" />
          </Accordion.Trigger>
        </Accordion.Header>
        <Accordion.Content class="accordion-default-content">
          leve-ui is a headless UI component library built for Qwik with full WAI-ARIA compliance.
        </Accordion.Content>
      </Accordion.Item>

      <Accordion.Item value="item-2" class="accordion-default-item">
        <Accordion.Header class="accordion-default-header">
          <Accordion.Trigger class="accordion-default-trigger">
            <span>Is it accessible?</span>
            <LuChevronDown class="accordion-default-chevron" aria-hidden="true" />
          </Accordion.Trigger>
        </Accordion.Header>
        <Accordion.Content class="accordion-default-content">
          Yes, all components follow WAI-ARIA Authoring Practices Guide (APG) patterns and keyboard
          interactions.
        </Accordion.Content>
      </Accordion.Item>

      <Accordion.Item value="item-3" class="accordion-default-item">
        <Accordion.Header class="accordion-default-header">
          <Accordion.Trigger class="accordion-default-trigger">
            <span>Can I customize the styles?</span>
            <LuChevronDown class="accordion-default-chevron" aria-hidden="true" />
          </Accordion.Trigger>
        </Accordion.Header>
        <Accordion.Content class="accordion-default-content">
          Yes, leve-ui components are headless and unstyled. You can style them using CSS, Tailwind,
          or any CSS-in-JS library.
        </Accordion.Content>
      </Accordion.Item>
    </Accordion.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/accordion

Anatomy#

import { Accordion } from '@leve-ui/accordion'; // or '@leve-ui/core'

<Accordion.Root>
  <Accordion.Item value="item-1">
    <Accordion.Header>
      <Accordion.Trigger />
    </Accordion.Header>
    <Accordion.Content />
  </Accordion.Item>
</Accordion.Root>
PartElementDescription
Accordion.Root<div>Wraps the items and holds which ones are open.
Accordion.Item<div>One pair of a header and its content, identified by value.
Accordion.Header<h1>–<h6>The heading that wraps the trigger. The level is set by level (default 3).
Accordion.Trigger<button>Shows or hides the content.
Accordion.Content<div>The section of content. Hidden while the item is closed.

Examples#

Multiple#

With type="multiple", any number of items can be open at once.

leve-ui is a headless UI component library built for Qwik with full WAI-ARIA compliance.

Collapsible#

With collapsible, the open item can be closed by activating its trigger again.

leve-ui is a headless UI component library built for Qwik with full WAI-ARIA compliance. Learn more about leve-ui

Disabled#

disabled on an Accordion.Item disables that item. disabled on the Root disables all items.

Controlled#

Pass a signal to bind:value to read and change the open items from outside.

leve-ui is a headless UI component library built for Qwik with full WAI-ARIA compliance.

Open items: item-1

API Reference#

Root#

PropDefaultType
type'single''single' | 'multiple'

How many items can be open at once. - 'single': at most one item - 'multiple': any number of items

defaultValue[]string[]

The values of the items that are open initially (uncontrolled).

bind:value–Signal<string[]>

A signal with the values of the open items (controlled).

onValueChange$–QRL<(value: string[]) => void>

Called when the user opens or closes an item.

collapsiblefalseboolean

When type is 'single', allows closing the open item by activating it again.

disabledfalseboolean

Disables all items.

orientation'vertical''vertical' | 'horizontal'

The orientation of the accordion, which decides the arrow keys that move focus.

looptrueboolean

Whether arrow keys wrap from the last trigger to the first and vice versa.

Also accepts all <div> attributes.

Data attributeValue
data-leve-accordionAlways present
data-orientation"vertical" | "horizontal"
data-disabledPresent when the Root is disabled

The open items are uncontrolled with defaultValue, or controlled with bind:value. onValueChange$ is called when the user opens or closes an item.

Item#

PropDefaultType
value (required)–string

A unique value that identifies this item.

disabledfalseboolean

Disables this item.

Also accepts all <div> attributes.

Data attributeValue
data-leve-accordion-itemAlways present
data-state"open" | "closed"
data-disabledPresent when the item or the Root is disabled
data-orientation"vertical" | "horizontal"
PropDefaultType
level31 | 2 | 3 | 4 | 5 | 6

The heading level (1–6) of the element that wraps the trigger.

Also accepts all <h1>–<h6> attributes.

Data attributeValue
data-leve-accordion-headerAlways present
data-state"open" | "closed"
data-disabledPresent when the item is disabled
data-orientation"vertical" | "horizontal"

Trigger#

No props of its own. Accepts all <button> attributes.

Data attributeValue
data-leve-accordion-triggerAlways present
data-state"open" | "closed"
data-disabledPresent when the item is disabled
data-orientation"vertical" | "horizontal"

A disabled item's trigger gets the native disabled attribute.

Content#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-accordion-contentAlways present
data-state"open" | "closed"
data-disabledPresent when the item is disabled
data-orientation"vertical" | "horizontal"

The content has the hidden attribute while the item is closed. It stays in the DOM so that the trigger's aria-controls keeps pointing to it.

Accessibility#

Complies with the Accordion WAI-ARIA design pattern.

  • Accordion.Trigger is a <button type="button"> with aria-expanded and aria-controls pointing to its content.
  • Accordion.Content has role="region" and aria-labelledby pointing to its trigger. IDs are generated with useId().
  • Choose a level on Accordion.Header that fits the heading structure of the page.
  • When type is "single" and collapsible is false, the trigger of the open item has aria-disabled="true", because it cannot be closed.
  • Disabled triggers are skipped by Tab and the arrow keys.

Keyboard Interactions#

KeyDescription
Enter / SpaceOpens or closes the item of the focused trigger.
Tab / Shift+TabMoves focus to the next or previous focusable element.
ArrowDown / ArrowUpWhen orientation is "vertical", moves focus to the next or previous trigger.
ArrowRight / ArrowLeftWhen orientation is "horizontal", moves focus to the next or previous trigger (reversed in right-to-left text).
Home / EndMoves focus to the first or last trigger.

The arrow keys wrap from the last trigger to the first and back while loop is true (the default).