Skip to content
Browse documentation
whisk/ui

Accordion

Reveal and hide related sections of content.

Overview

Accordion reveals optional related sections without leaving the current page. Its named parts pair each heading button with one retained content region.

Use when

Related, optional sections can be revealed on demand without hiding essential information.

Use instead

Use headings and visible content when readers need to compare all sections at once.

Usage

Invoices and payment methods.
import {
  Accordion,
  AccordionBody,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@smoothie-framework/whisk-react";

<Accordion type="single" defaultValue="billing">
  <AccordionItem value="billing">
    <AccordionTrigger headingLevel={2}>Billing</AccordionTrigger>
    <AccordionContent>
      <AccordionBody>Invoices and payment methods.</AccordionBody>
    </AccordionContent>
  </AccordionItem>
</Accordion>

Examples

Keep one section open

Single selection is the default. With collapsible unset, the open section stays open, which works well when one detail section should always remain visible.

Delivery options and tracking.

Return eligibility and refund timing.
import {
  Accordion,
  AccordionBody,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@smoothie-framework/whisk-react";

<Accordion defaultValue="shipping">
  <AccordionItem value="shipping">
    <AccordionTrigger headingLevel={2}>Shipping</AccordionTrigger>
    <AccordionContent><AccordionBody>Delivery options and tracking.</AccordionBody></AccordionContent>
  </AccordionItem>
  <AccordionItem value="returns">
    <AccordionTrigger headingLevel={2}>Returns</AccordionTrigger>
    <AccordionContent><AccordionBody>Return eligibility and refund timing.</AccordionBody></AccordionContent>
  </AccordionItem>
</Accordion>

Let every section close

Set collapsible in single mode when no open section is also a valid state. The callback receives an empty string after the open item closes.

Manage sign-in protection.
import {
  Accordion,
  AccordionBody,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@smoothie-framework/whisk-react";

<Accordion type="single" collapsible defaultValue="security">
  <AccordionItem value="security">
    <AccordionTrigger headingLevel={2}>Security</AccordionTrigger>
    <AccordionContent><AccordionBody>Manage sign-in protection.</AccordionBody></AccordionContent>
  </AccordionItem>
</Accordion>

Open several related sections

Use type="multiple" when sections are independently useful. Multiple mode always permits closing, so it does not accept collapsible.

Choose which updates to receive.

View invoices and payment methods.
import {
  Accordion,
  AccordionBody,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@smoothie-framework/whisk-react";

<Accordion type="multiple" defaultValue={["notifications", "billing"]}>
  <AccordionItem value="notifications">
    <AccordionTrigger headingLevel={2}>Notifications</AccordionTrigger>
    <AccordionContent><AccordionBody>Choose which updates to receive.</AccordionBody></AccordionContent>
  </AccordionItem>
  <AccordionItem value="billing">
    <AccordionTrigger headingLevel={2}>Billing</AccordionTrigger>
    <AccordionContent><AccordionBody>View invoices and payment methods.</AccordionBody></AccordionContent>
  </AccordionItem>
</Accordion>

Control the open item from application state

Use value with onValueChange when another part of the application owns the selection. The callback requests a change; update value to accept it. Do not also pass defaultValue.

tsx
import {
  Accordion,
  AccordionBody,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@smoothie-framework/whisk-react";

type SettingsAccordionProps = {
  openSection: string;
  onOpenSectionChange: (value: string) => void;
};

export function SettingsAccordion({
  openSection,
  onOpenSectionChange,
}: SettingsAccordionProps) {
  return (
    <Accordion value={openSection} onValueChange={onOpenSectionChange}>
      <AccordionItem value="profile">
        <AccordionTrigger headingLevel={2}>Profile</AccordionTrigger>
        <AccordionContent><AccordionBody>Profile settings</AccordionBody></AccordionContent>
      </AccordionItem>
      <AccordionItem value="security">
        <AccordionTrigger headingLevel={2}>Security</AccordionTrigger>
        <AccordionContent><AccordionBody>Security settings</AccordionBody></AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}

Use the built-in panel structure

AccordionContent remains mounted while it is closed so height animation can be measured. Put padding and the panel surface in AccordionBody rather than on AccordionContent.

Support is available Monday to Friday.
import {
  Accordion,
  AccordionBody,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@smoothie-framework/whisk-react";

<Accordion type="single" collapsible>
  <AccordionItem id="support" value="support">
    <AccordionTrigger headingLevel={2} indicator={null}>
      Contact support
    </AccordionTrigger>
    <AccordionContent>
      <AccordionBody>Support is available Monday to Friday.</AccordionBody>
    </AccordionContent>
  </AccordionItem>
</Accordion>

Props

Component props

PropTypeDefaultDescription
Accordion: typesingle | multiplesingleAllow one open item or several open items. New code should use type rather than the legacy multiple boolean.
Accordion: value | defaultValuestring | readonly string[]"" | []Control or initialize open values. Use one string in single mode and an array in multiple mode. Pass only one of value and defaultValue.
Accordion: collapsiblebooleanfalseAllow the open item to close in single mode. Multiple mode always permits closing.
Accordion: onValueChange(value: string | readonly string[]) => voidnoneReceive a requested selection change. In controlled mode, update value yourself to accept it.
Accordion: disabledbooleanfalseDisable every item in the accordion.
Accordion: size | variantsm | md | lg; outline | subtle | enclosed | plainmd; outlineChoose responsive density and appearance.
AccordionItem: valuestringnoneRequired unique, non-empty item identifier. Put id on AccordionItem when the generated trigger and content IDs need a stable prefix.
AccordionItem: disabledbooleanfalseDisable one item without disabling the whole accordion.
AccordionTrigger: headingLevel1 | 2 | 3 | 4 | 5 | 6noneRequired heading rank. Match it to the surrounding document outline.
AccordionTrigger: startElement | indicatorReactNodenoneAdd decorative trigger content. Omit indicator for the default chevron; pass null to hide it. Do not place controls in either slot.
AccordionContent | AccordionBodynative div propsnoneAccordionContent is the labelled panel region. Use AccordionBody inside it for the padded content surface.
AccordionIndicatornative span propsnoneRender the default decorative chevron or supply another decorative indicator.
native props | classNameHTML attributesnoneAccordion, item, and content accept their matching native attributes, classes, and refs. Trigger accepts native button attributes and defaults to type="button".

Accessibility

AccordionTrigger renders a native button inside the heading selected by headingLevel. AccordionContent is a labelled region connected to its trigger, so do not manually recreate those ARIA relationships. Enter and Space activate the focused trigger; Arrow keys, Home, and End move focus among available triggers. Decorative start elements and indicators are hidden from assistive technology. Closed panels remain mounted, and reduced-motion users do not receive the height animation. Keep essential information outside collapsed panels when people need to compare it or find it quickly.

Content guidance

Write each trigger as the topic it reveals. Keep essential information out of collapsed panels when readers need to compare it.