Accordion

Components/Overlay and disclosure

ImplementationHTML/CSS/JSArk/ZagReact · shadcn/Base UIAngular

Organizes related content into sections that can be expanded or collapsed.

DesignUsageImplementationAccessibility

Documentation sectionDesignUsageImplementationAccessibility

Design

Functional preview

Running with the stable ds-tis/accordion JavaScript runtime.

Loading functional preview…

Open the HTML/CSS/JS playground

Anatomy

Configurações avançadas

Conteúdo expandido do painel.

1 2 3 4 5 6

1 .ds-accordion — group of related items.
2 .ds-accordion__item — visual container for each section.
3 .ds-accordion__trigger — button that toggles aria-expanded.
4 .ds-accordion__leading-icon — optional Lucide icon.
5 .ds-accordion__chevron — visual indicator for open/closed state.
6 .ds-accordion__panel — content slot associated with the trigger.

Default

Use a button for the trigger. The documentation helper synchronizes aria-expanded, hidden, and data-state; in product, keep the same contract.

Billing details

Invoices are generated on the first business day of each month and sent to account owners.

Security settings

Custom content

The panel is a slot. Compose complex content with public DS components instead of isolated internal classes.

Plano atual

Team Pro

Até 25 usuários, billing mensal e permissões avançadas.

Alterar plano

Disabled

Configuração bloqueada

Figma API

The live component set exposes Title, not Label. Use the public Figma property name for handoff and documentation; the CSS class remains .ds-accordion__title.

Property	Type	Repo equivalent
Title	TEXT	.ds-accordion__title
Content	TEXT	.ds-accordion__panel com texto simples
Content Slot	SLOT	Custom content inside .ds-accordion__panel.
Show Leading Icon	BOOLEAN	Render or omit .ds-accordion__leading-icon.
Leading Icon	INSTANCE_SWAP	Lucide icon with data-lucide.
State	VARIANT	Default, Hover, Focus, Disabled
Open	VARIANT	aria-expanded, hidden e data-state

Token mapping

Parte	CSS	Token atual
Item	.ds-accordion__item	component.accordion.item.{radius,border-width,bg,border-color}
Trigger	.ds-accordion__trigger	component.accordion.trigger.{height,padding,gap}
Title	.ds-accordion__title	component.accordion.trigger.content.color + typography body/md bold
Content	.ds-accordion__panel	component.accordion.content.{color,padding,gap}
Chevron	.ds-accordion__chevron	component.accordion.chevron.{size,color,stroke-width}
Leading icon	.ds-accordion__leading-icon	component.accordion.leading-icon.{size,color,stroke-width}
Focus ring	.ds-accordion__trigger:focus-visible	component.accordion.focus-ring.radius.default + component.focus-ring.*

Usage

When to use

Use Accordion when

Users need to compare or explore related sections, such as FAQs, grouped settings, progressive details, or secondary content that does not need to be fully visible at once.

Don't use Accordion when

Navigation switches primary views (use Tabs), the content is a command menu (use Menu/Action Menu), or the information must stay visible for decision making.

Best practices

Entrega

Endereço e janela de recebimento.

Pagamento

Faça

Group related content in collapsible sections with concise titles.

Visão geral

Informação essencial para decisão.

Não faça

Don't hide critical information in a closed accordion by default.

Related

Tabs Menu Card

Implementation

Status

Stable

Distribution

npm package

Installation

npm

npm install ds-tis

pnpm

pnpm add ds-tis

yarn

yarn add ds-tis

bun

bun add ds-tis

Imports

import 'ds-tis/css'
import { initAccordions } from 'ds-tis/accordion'

initAccordions()

Markup

<div class="ds-accordion" data-accordion-mode="single">
  <div class="ds-accordion__item" data-state="open">
    <button
      class="ds-accordion__trigger"
      type="button"
      id="billing-trigger"
      aria-expanded="true"
      aria-controls="billing-panel"
    >
      <span class="ds-accordion__title">Faturamento</span>
    </button>
    <div
      class="ds-accordion__panel"
      id="billing-panel"
      role="region"
      aria-labelledby="billing-trigger"
    >
      Gerencie formas de pagamento e dados fiscais.
    </div>
  </div>
</div>

Web implementation contract

Behavior

Contract	Rule
aria-expanded	State source on the trigger; true opens the associated panel.
hidden	Must be present on closed panels and absent on open panels.
data-state	Mirrors open/closed on the item for CSS, tests, and debugging.
data-accordion-mode="single"	Optional. Closes siblings when one item opens, matching patterns such as Radix Accordion single.

CSS classes

Class	Description
ds-accordion	Container for the item group.
ds-accordion__item	Visual container for one section.
ds-accordion__item--disabled	Disabled item — trigger with disabled.
ds-accordion__trigger	Button that toggles panel visibility.
ds-accordion__leading-icon	Optional Lucide icon before the title.
ds-accordion__title	Trigger text.
ds-accordion__chevron	Decorative state indicator.
ds-accordion__panel	Expanded content slot.
data-state	Synchronized item state: open or closed.

Required runtime

CSS defines anatomy and visual states, but expand/collapse, keyboard, and single mode depend on the public ds-tis/accordion module (initAccordions / destroyAccordions). Events: ds-accordion-open, ds-accordion-close. Call destroyAccordions on unmount.

Accessibility

Keyboard interaction

Key	Action
Tab	Moves focus between Accordion triggers and controls inside open panels.
Enter / Space	Toggles the panel associated with the focused trigger.
Arrow Up / Arrow Down	Moves focus between group triggers.
Home / End	Moves focus to the first or last trigger in the group.

Accessibility

Rule	Application
button	The trigger must be a real button, not a clickable div.
aria-expanded	Reflects the open/closed state on the trigger.
aria-controls	Points to the controlled panel id.
role="region"	Use on panels with enough content to merit a landmark, always with aria-labelledby.
hidden	Removes closed panels from the accessibility tree.
disabled	Removes unavailable triggers from interaction and the tab order.

Output responsibility

Initialize the public runtime after render and destroy it when the owning view unmounts.

Validation evidence

Covered by the stable Storybook, public runtime tests when applicable, keyboard scenarios, responsive checks, and Axe.

Open the stable reference