Accordion

Overview

Accordion é uma pilha vertical de seções expansíveis. Use quando há várias perguntas/blocos relacionados e o leitor quer pular entre eles sem trocar de página — FAQs, configurações em grupos, breakdowns de release notes.

A diferença em relação a Tabs é estrutural: Accordion preserva contexto vertical (todas as seções continuam visíveis no scroll), Tabs trocam o painel inteiro. Quando os irmãos precisam continuar visíveis, Accordion vence.

Anatomy

<Accordion type="single" | "multiple">
  └─ <AccordionItem value="x">
       ├─ <AccordionTrigger>  ← header clicável + chevron rotativo
       └─ <AccordionContent>  ← seção animada (open/close)
</Accordion>

Usage

import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger
} from "@kalvner/kds/display/accordion";

export function Faq() {
  return (
    <Accordion type="single" collapsible>
      <AccordionItem value="q1">
        <AccordionTrigger>Pergunta?</AccordionTrigger>
        <AccordionContent>Resposta.</AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}

Props

Accordion (Root)

AccordionItem · AccordionTrigger · AccordionContent

Subcomponents

• AccordionItem — wrapper de um par trigger + content; carrega o value que identifica o item.
• AccordionTrigger — header clicável; o chevron embutido rotaciona no data-state=open.
• AccordionContent — região revelada; animada via data-[state=closed]:animate-accordion-up e accordion-down.

Variants

States

Composition

Accordion combina bem com Card (cada item dentro de um cartão para hierarquia visual mais forte) ou Sidebar Section (grupos colapsáveis na navegação lateral). Não aninhe além de 2 níveis — vira caça ao tesouro.

When to use

• FAQ com 5+ perguntas relacionadas.
• Configurações agrupadas (Conta, Faturamento, Notificações).
• Release notes ou changelogs por versão.
• Filtros laterais com seções colapsáveis.

When not to use

• Quando há um único bloco que expande — use Collapsible.
• Quando trocar a seção significa trocar todo o painel — use Tabs.
• Para conteúdo crítico que precisa estar sempre visível — Accordion esconde por padrão.

Best practices

• Headers descrevem o conteúdo, não a ação ("O que é o KDS?", não "Clique para expandir").
• Em FAQ, prefira type="single" collapsible — só uma resposta visível evita parede de texto.
• O primeiro item pode vir aberto (defaultValue="item-1") quando há uma resposta dominante.
• Não esconda CTAs primários atrás de Accordion. Se o usuário precisa vê-lo, mostre fora.

Accessibility

Related

• Collapsible — primitivo subjacente, uma única seção.
• Tabs — quando trocar implica painel inteiro.
• Sidebar — usa Collapsible para grupos navegáveis.