Skip to main content

Accordion

A collapsible content component that supports single or multiple panel expansion with keyboard navigation and full accessibility support.

Live Demo​

JavaScript
<div className='accordion-demo-container'>
    <Accordion.Root className='accordion' defaultValue="2">
      <Accordion.Item className='accordion-item' value="1">
        <Accordion.Header className='accordion-header'>
          <Accordion.Trigger className='accordion-trigger'>
            <span className='accordion-icon'></span>
            <span className='accordion-title'>Accordion</span>
            <div className='accordion-expand'>
              <svg className='accordion-expand-icon' xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none">
                <path d="M13.2292 7.49998L9.99583 10.7333L6.7625 7.49998C6.4375 7.17498 5.9125 7.17498 5.5875 7.49998C5.2625 7.82498 5.2625 8.34998 5.5875 8.67498L9.4125 12.5C9.7375 12.825 10.2625 12.825 10.5875 12.5L14.4125 8.67498C14.7375 8.34998 14.7375 7.82498 14.4125 7.49998C14.0875 7.18331 13.5542 7.17498 13.2292 7.49998Z"/>
              </svg> 
            </div>
          </Accordion.Trigger>
        </Accordion.Header>
        <Accordion.Content className='accordion-content'>
          Accordion content can be customized to fit the surrounding interface.
        </Accordion.Content>
      </Accordion.Item>
      <Accordion.Item className='accordion-item' value="2">
        <Accordion.Header className='accordion-header'>
          <Accordion.Trigger className='accordion-trigger'>
            <span className='accordion-icon'></span>
            <span className='accordion-title'>Accordion</span>
            <div className='accordion-expand'>
              <svg className='accordion-expand-icon' xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none">
                <path d="M13.2292 7.49998L9.99583 10.7333L6.7625 7.49998C6.4375 7.17498 5.9125 7.17498 5.5875 7.49998C5.2625 7.82498 5.2625 8.34998 5.5875 8.67498L9.4125 12.5C9.7375 12.825 10.2625 12.825 10.5875 12.5L14.4125 8.67498C14.7375 8.34998 14.7375 7.82498 14.4125 7.49998C14.0875 7.18331 13.5542 7.17498 13.2292 7.49998Z"/>
              </svg> 
            </div>
          </Accordion.Trigger>
        </Accordion.Header>
        <Accordion.Content className='accordion-content'>
          Accordion content can be customized to fit the surrounding interface.
        </Accordion.Content>
      </Accordion.Item>
      <Accordion.Item className='accordion-item' value="3">
        <Accordion.Header className='accordion-header'>
          <Accordion.Trigger className='accordion-trigger'>
            <span className='accordion-icon'></span>
            <span className='accordion-title'>Accordion</span>
            <div className='accordion-expand'>
             <svg className='accordion-expand-icon' xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none">
                <path d="M13.2292 7.49998L9.99583 10.7333L6.7625 7.49998C6.4375 7.17498 5.9125 7.17498 5.5875 7.49998C5.2625 7.82498 5.2625 8.34998 5.5875 8.67498L9.4125 12.5C9.7375 12.825 10.2625 12.825 10.5875 12.5L14.4125 8.67498C14.7375 8.34998 14.7375 7.82498 14.4125 7.49998C14.0875 7.18331 13.5542 7.17498 13.2292 7.49998Z"/>
              </svg> 
            </div>
          </Accordion.Trigger> 
        </Accordion.Header>
        <Accordion.Content className='accordion-content'>
          Accordion content can be customized to fit the surrounding interface.
        </Accordion.Content>
      </Accordion.Item>
    </Accordion.Root>
  </div>

The live demo shows a single-expand accordion with custom trigger content, an inline icon, and rotating chevron feedback.

Features​

  • ✅ Single or multiple panel expansion modes
  • ✅ Controlled and uncontrolled state management
  • ✅ Optional collapsible behavior for single mode
  • ✅ Disabled state support for individual items or entire accordion
  • ✅ Semantic heading structure with configurable heading levels
  • ✅ Horizontal and vertical orientation support
  • ✅ Polymorphic component support with as prop
  • ✅ Force mount option for content preservation

Import​

import { Accordion } from '@turkish-technology/spar';

Anatomy​

The Accordion component is built as a compound component with multiple parts:

Accordion content can be customized to fit the surrounding interface.

Parts
RootRoot context provider
ItemSingle collapsible section
HeaderSemantic heading wrapper
TriggerToggle button
ContentCollapsible content panel

Structure​

<Accordion.Root>
<Accordion.Item value="item-1">
<Accordion.Header>
<Accordion.Trigger>...</Accordion.Trigger>
</Accordion.Header>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion.Root>

Data Flow:

  • Accordion: Root context provider that manages state
  • Accordion.Item: Represents a single collapsible section
  • Accordion.Header: Semantic heading wrapper for proper document structure
  • Accordion.Trigger: Button to toggle the item
  • Accordion.Content: Panel revealed when open

Code Examples​

Basic Single Panel Accordion​

Basic accordion that allows only one panel to be expanded at a time:

export function BasicAccordion() {
return (
<Accordion.Root>
<Accordion.Item value="a">
<Accordion.Header>
<Accordion.Trigger>Toggle A</Accordion.Trigger>
</Accordion.Header>
<Accordion.Content>Panel A</Accordion.Content>
</Accordion.Item>
<Accordion.Item value="b">
<Accordion.Header>
<Accordion.Trigger>Toggle B</Accordion.Trigger>
</Accordion.Header>
<Accordion.Content>Panel B</Accordion.Content>
</Accordion.Item>
</Accordion.Root>
);
}

Multiple Panel Expansion​

Accordion that allows multiple panels to be expanded simultaneously:

<Accordion.Root multiple defaultValue={['a']}>
<Accordion.Item value="a">
<Accordion.Header>
<Accordion.Trigger>Section A</Accordion.Trigger>
</Accordion.Header>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
<Accordion.Item value="b">
<Accordion.Header>
<Accordion.Trigger>Section B</Accordion.Trigger>
</Accordion.Header>
<Accordion.Content>...</Accordion.Content>
</Accordion.Item>
</Accordion.Root>

Controlled State Management​

Accordion with external state control and change handling:

const [openItems, setOpenItems] = React.useState<string[]>(['a']);

<Accordion.Root multiple value={openItems} onValueChange={setOpenItems}>
{/* ...items */}
</Accordion.Root>;

API Reference​

Accordion / Accordion.Root​

The root container that provides context and manages the state for all accordion items within it. Accordion and Accordion.Root are the same component - the difference is only import/notation style.

Props

NameTypeDefaultDescription
multiple?booleanfalseWhether multiple panels can be expanded simultaneously
collapsible?booleantrueWhether panels can be collapsed (only for single mode)
value?string | number | (string | number)[]undefinedControlled state - single value or array for multiple
defaultValue?string | number | (string | number)[]undefinedUncontrolled initial state
onValueChange?(value: string | number | (string | number)[]) => voidundefinedCallback when state changes
disabled?booleanfalseDisables all accordion items
orientation?"vertical" | "horizontal""vertical"Orientation for keyboard navigation
as?React.ElementType"div"Polymorphic component type
childrenReact.ReactNode-Accordion.Item components

Events

NameParametersDescriptionWhen Triggered
onValueChange(value: string | string[])State changes when panels expand/collapseUser interaction or programmatic change

HTML Attributes

AttributeValuePurpose
data-orientation"vertical" | "horizontal"Indicates navigation orientation
data-selection-mode"single" | "multiple"Indicates the expansion mode

Accordion.Item​

Individual accordion item that contains a header and content panel.

Props

NameTypeDefaultDescription
valuestring-Unique identifier for the item
id?stringundefinedCustom base ID for ARIA relationships; derives trigger and content IDs
disabled?booleanfalseDisables this specific item
as?React.ElementType"div"Polymorphic component type
childrenReact.ReactNode-Accordion.Header and Accordion.Content components

Events

NameParametersDescriptionWhen Triggered
None-Item manages internal state through context-

HTML Attributes

AttributeValuePurpose
data-state"open" | "closed"Reflects the expansion state of the item
data-disabled""Present when the item is disabled

Accordion.Header​

Semantic heading wrapper for the accordion trigger button.

Props

NameTypeDefaultDescription
level?number3Heading level (1-6) for document hierarchy
as?React.ElementType"h3"Polymorphic component type (heading element)
childrenReact.ReactNode-Accordion.Trigger component

Events

NameParametersDescriptionWhen Triggered
None-Header is purely semantic-

HTML Attributes

AttributeValuePurpose
data-state"open" | "closed"Reflects the expansion state of the item
data-levelnumberReflects the rendered heading level
data-disabled""Present when the item is disabled

Accordion.Trigger​

Button that toggles the visibility of the associated content panel.

Props

NameTypeDefaultDescription
as?React.ElementType"button"Polymorphic component type
childrenReact.ReactNode | ((state: AccordionTriggerRenderProps) => React.ReactNode)-Trigger content or render props function
onClick?(event: React.MouseEvent) => voidundefinedCustom click handler
onKeyDown?(event: React.KeyboardEvent) => voidundefinedCustom keydown handler

Render Props (AccordionTriggerRenderProps)

PropertyTypeDescription
isOpenbooleanWhether the accordion item is currently expanded
disabledbooleanWhether the trigger is disabled
open() => voidFunction to programmatically open the accordion item
close() => voidFunction to programmatically close the accordion item
toggle() => voidFunction to programmatically toggle the accordion item

Events

NameParametersDescriptionWhen Triggered
onClick(event: React.MouseEvent)Trigger clickedMouse click on trigger
onKeyDown(event: React.KeyboardEvent)Key pressed on triggerKeyboard interaction

HTML Attributes

AttributeValuePurpose
idstringUnique identifier matching the trigger element ARIA ID
aria-expandedbooleanIndicates whether the associated panel is expanded
aria-controlsstringReferences the content panel element ID
data-state"open" | "closed"Reflects the expansion state of the item
data-disabled""Present when the trigger is disabled
data-accordion-trigger""Always present; identifies the element as an accordion trigger
data-valuestringThe value of the accordion item this trigger belongs to

Accordion.Content​

Collapsible panel containing the accordion item content.

Props

NameTypeDefaultDescription
forceMount?booleanfalseForce content to remain mounted when collapsed
onBeforeMatch?(event: Event) => voidundefinedCallback fired when content is found via browser Find command
as?React.ElementType"div"Polymorphic component type
childrenReact.ReactNode-Panel content

Events

NameParametersDescriptionWhen Triggered
onBeforeMatch(event: Event)Fired when hidden content is matched via browser Find commandBrowser Find (Ctrl+F/Cmd+F) matches content inside a closed, forceMounted panel

HTML Attributes

AttributeValuePurpose
idstringUnique identifier matching the content element ARIA ID
role"region"Always present; marks the panel as a landmark region
aria-labelledbystringReferences the trigger element that labels this panel
data-state"open" | "closed"Reflects the visibility state of the panel
data-disabled""Present when the item is disabled
hiddentrue | "until-found"Present when closed and forceMount is true; "until-found" in modern browsers, true as fallback

Keyboard Interactions​

Complete keyboard behavior for the accordion component:

KeyActionContextNotes
TabNavigateAlwaysMoves focus to next focusable element in DOM order
Shift + TabNavigate backwardAlwaysMoves focus to previous focusable element
EnterToggle panelFocused triggerExpands/collapses the associated panel
SpaceToggle panelFocused triggerAlternative activation method for triggers
ArrowDownNext triggerFocused trigger (vertical)Moves focus to the next enabled trigger in DOM order; wraps and skips disabled items
ArrowUpPrevious triggerFocused trigger (vertical)Moves focus to the previous enabled trigger in DOM order; wraps and skips disabled items
ArrowRightNext triggerFocused trigger (horizontal)Moves focus to the next enabled trigger in DOM order; wraps and skips disabled items
ArrowLeftPrevious triggerFocused trigger (horizontal)Moves focus to the previous enabled trigger in DOM order; wraps and skips disabled items
HomeFirst triggerFocused triggerMoves focus to the first enabled trigger
EndLast triggerFocused triggerMoves focus to the last enabled trigger