Skip to content
+

Accordion

The Open UI Kit Accordion lets users expand and collapse sections of related content with product-ready spacing, typography, and theme behavior.

Introduction

Accordion is a disclosure surface for content that should stay available without taking over the page. Use it for grouped settings, page sections, filters, summaries, and optional details that users can scan before opening.

Open UI Kit keeps the expected accordion behavior and adds a simpler header contract:

  • title renders the main summary label.
  • subTitle renders supporting summary text.
  • children renders the expandable content.
  • Standard accordion props such as defaultExpanded, expanded, onChange, and disabled still work.

Review the basic settings that identify this workspace across the product.

Manage who can access this workspace and what they can change.

Decide which product events should notify the team.

Import

import { Accordion } from '@open-ui-kit/core';

When to use

Use Accordion when related content should stay available without taking over the page. It works well for settings groups, filters, summaries, policy details, and optional sections that users can scan before opening.

Avoid Accordion for primary navigation, required step-by-step tasks, or content that must be visible for the page to make sense.

Anatomy

An accordion is made of a summary button and a details region. The summary should identify the section with a short title and, when useful, a supporting subTitle or status. The details region should hold the form fields, explanations, lists, or actions that belong to that section.

Arrow position

Use arrowPosition to place the disclosure icon on the left or right side of the summary. Left is the default and works well for dense lists. Right keeps the label aligned with surrounding content.

Left arrow

Use the default left arrow when the accordion behaves like a list item.

Right arrow

Use a right arrow when the summary text should align with surrounding content.

Size

Use size="large" for page-level sections and size="medium" for compact lists, drawers, and settings panels.

Large

Large accordions work well for page-level sections and readable content groups.

Medium

Medium accordions are more compact for drawers, panels, and dense settings.

Contained

Use contained when each item needs a visible surface. This is useful inside cards, side panels, and stacked configuration blocks.

Contained accordions add a visible surface around each disclosure item.

Keep related controls visually grouped without adding another card.

Dividers

Medium uncontained accordions show a divider between the title and subtitle by default. Use showDivider when a large accordion also needs that separation, or set it to false to keep compact summaries visually lighter.

Medium default divider

Medium uncontained accordions show a divider by default to keep dense rows easy to scan.

Forced divider

Use showDivider when a large summary needs stronger separation between the title and subtitle.

Summary content

The summary can include icons, custom slots, actions, and an end slot. Use these extras for short metadata or contextual actions that help users decide whether to open the panel.

Add icons and action content when the summary needs extra context without opening the panel.

Slots are useful for badges, counters, instance labels, and other compact metadata.

Disabled

Use the disabled prop on the Accordion component to disable interaction and focus.

This section can be expanded and collapsed.

Disabled accordions keep the content unavailable and remove keyboard interaction.

Controlled Accordion

The Accordion component can be controlled or uncontrolled.

Controlled accordions are useful when only one section should stay open.

Store the active panel in parent state and pass `expanded` plus `onChange` to each item.

You can also set the state to `false` to collapse every section.

Behavior notes

Use defaultExpanded for simple uncontrolled panels. Use expanded and onChange when expansion needs to sync with a URL, form state, saved preference, or analytics event. Keep summary content short so collapsed panels remain easy to scan.

Props

The Open UI Kit Accordion keeps familiar disclosure behavior and adds a small set of product defaults:

Prop Type Default Description
title string - Required summary label.
subTitle string - Optional supporting text in the summary row.
titleStartIcon ReactNode - Optional icon rendered before the title.
titleEndIcon ReactNode - Optional icon rendered after the title.
titleSlot ReactNode - Optional inline content rendered after the title.
subTitleStartIcon ReactNode - Optional icon rendered before the subtitle.
subTitleEndIcon ReactNode - Optional icon rendered after the subtitle.
subTitleSlot ReactNode - Optional inline content rendered after the subtitle.
action ReactNode - Optional right-side summary action, such as a link label.
endSlot ReactNode - Optional final summary content after the action.
size 'medium' | 'large' 'large' Controls summary typography and spacing.
arrowPosition 'left' | 'right' 'left' Places the expand indicator before or after the content.
contained boolean false Renders the item as a bordered surface.
showDivider boolean size === 'medium' && !contained Controls the summary divider between title and subtitle.
useDotsStyle boolean false Applies a dotted outline to the details content box.
accordionSummaryProps AccordionSummaryProps - Passes props to the internal summary button.
detailsContentBoxProps BoxProps - Passes props to the inner content wrapper.

Accessibility

Accordion uses standard disclosure semantics, including keyboard support for Enter and Space. Add stable id and aria-controls values through accordionSummaryProps when the accordion needs explicit labels.

<Accordion
  title="Billing settings"
  subTitle="Payment method and invoice recipients"
  accordionSummaryProps={{
    id: 'billing-settings-header',
    'aria-controls': 'billing-settings-content',
  }}
>
  Billing content
</Accordion>

Performance

The Accordion content is mounted by default even if it's not expanded. This default behavior has server-side rendering and SEO in mind.

If you render the Accordion Details with a big component tree nested inside, or if you have many Accordions, you may want to change this behavior by setting unmountOnExit to true inside the slotProps.transition prop to improve performance:

<Accordion
  title="Audit log"
  slotProps={{ transition: { unmountOnExit: true } }}
/>

Usage guidance

  • Use Accordion for optional details, not required instructions.
  • Keep the summary readable without opening the panel.
  • Use contained when the item needs to feel like a standalone surface.
  • Use controlled state when expansion syncs with routing, forms, telemetry, or saved preferences.
  • Avoid destructive actions in the summary unless the action is explicit and confirmed elsewhere.