Collapse
Visão Geral
O componente br-collapse é o controle retrátil do GovBR-DS baseado no elemento semântico HTML5 <details>, desenvolvido para permitir que a pessoa usuária expanda ou recolha seções de conteúdo sob demanda.
Para que serve
- Otimização de espaço e hierarquia: Reduz a sobrecarga de informação inicial na tela, ocultando blocos secundários até que o usuário decida visualizá-los.
- Estruturação de perguntas e respostas: Padrão oficial para construção de seções de FAQ (perguntas frequentes) e listas explicativas sanfonadas (accordion).
- Acessibilidade nativa: Por utilizar internamente os elementos
<details>e<summary>, possui controle total de teclado, estado acessível (open) e anúncios para tecnologias assistivas sem exigir scripts adicionais complexos.
Quando utilizar
- Utilize quando:
- O conteúdo for extenso, dividido em tópicos independentes e a maioria dos usuários só precisa consultar itens específicos.
- Houver seções complementares opcionais em um formulário longo.
- Evite e prefira outro componente quando:
- A informação contida for crítica para a tomada de decisão imediata ou segurança da pessoa usuária (ela deve ficar permanentemente visível).
- A intenção for alternar entre diferentes visões de uma mesma tela completa (prefira
br-tab).
Estrutura e Slots
O br-collapse organiza o acionamento e a área expansível:
trigger: Slot para personalizar o botão/gatilho de expansão (texto, ícones ou componentes de apoio dentro do summary).default: Slot para inserção do conteúdo que é revelado quando o componente é expandido.
Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.
Exemplo(s)
Propriedades
accordionGroup
| Atributo | accordion-group |
|---|---|
| Descrição | Identifica o grupo de accordion; quando informado, mantém apenas um item aberto por vez entre os irmãos do mesmo pai imediato. |
| Tipo | string |
| Valor padrão | null |
colorMode
| Atributo | color-mode |
|---|---|
| Descrição | Tema visual do Collapse/Accordion. |
| Tipo | "dark" | "light" |
| Valor padrão | 'light' |
customId
| Atributo | custom-id |
|---|---|
| Descrição | Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId(). |
| Tipo | string |
| Valor padrão | generateUniqueId() |
divider
| Atributo | divider |
|---|---|
| Descrição | Indica se o componente possui um divisor (divider) inferior. |
| Tipo | boolean |
| Valor padrão | false |
expansionDirection
| Atributo | expansion-direction |
|---|---|
| Descrição | Direção em que o conteúdo é expandido e para a qual o ícone aponta. |
| Tipo | "down" | "left" | "right" | "up" |
| Valor padrão | 'down' |
iconPosition
| Atributo | icon-position |
|---|---|
| Descrição | Define a posição do ícone no acionador: 'left' ou 'right'. |
| Tipo | "left" | "right" |
| Valor padrão | 'right' |
iconToHide
| Atributo | icon-to-hide |
|---|---|
| Descrição | Identificador Iconify do ícone exibido quando o conteúdo está visível. O valor padrão usa o registro SVG local. Para ícones por classe CSS, use o slot icon-to-hide. |
| Tipo | string |
| Valor padrão | 'fa6-solid:chevron-up' |
iconToShow
| Atributo | icon-to-show |
|---|---|
| Descrição | Identificador Iconify do ícone exibido quando o conteúdo está oculto. O valor padrão usa o registro SVG local. Para ícones por classe CSS, use o slot icon-to-show. |
| Tipo | string |
| Valor padrão | 'fa6-solid:chevron-down' |
open
| Atributo | open |
|---|---|
| Descrição | Controla se o collapse está aberto. |
| Tipo | boolean |
| Valor padrão | false |
triggerVariant
| Atributo | trigger-variant |
|---|---|
| Descrição | Forma visual do acionador sem alterar sua semântica nativa. |
| Tipo | "button" | "surface" | "text" |
| Valor padrão | 'surface' |
useIcons
| Atributo | use-icons |
|---|---|
| Descrição | Controla se o identificador visual de expansão/retração será renderizado. |
| Tipo | boolean |
| Valor padrão | true |
Slots
| Nome | Descrição |
|---|---|
"default" | Slot para o conteúdo expansível exibido ao abrir o collapse. |
"icon-to-hide" | Ícone exibido quando o conteúdo está visível. Forma preferida para ícones por classe CSS; tem precedência sobre a prop iconToHide. |
"icon-to-show" | Ícone exibido quando o conteúdo está oculto (ex.: <i slot="icon-to-show" class="fas fa-plus"></i>). Forma preferida para ícones por classe CSS; tem precedência sobre a prop iconToShow. |
"trigger" | Slot para personalizar o acionador (texto, ícones, imagens, etc.). |
Eventos
| Evento | Descrição | Depreciação | Propagação |
|---|---|---|---|
brCollapseClose | Evento canônico emitido ao recolher. | --- | true |
brCollapseOpen | Evento canônico emitido ao expandir. | --- | true |
brDidClose | Use brCollapseClose. | true | |
brDidOpen | Use brCollapseOpen. | true |
Métodos
closeCollapse
| Descrição | Fecha o collapse programaticamente. |
|---|---|
| Assinatura | closeCollapse() => Promise<void> |
| Depreciação | Atualize a propriedade open. |
| Parâmetros | --- |
openCollapse
| Descrição | Abre o collapse programaticamente. |
|---|---|
| Assinatura | openCollapse() => Promise<void> |
| Depreciação | Atualize a propriedade open. |
| Parâmetros | --- |
toggle
| Descrição | Alterna o estado aberto. O elemento também redispara o evento nativo toggle no host; essa ocorrência é sintética (isTrusted === false). |
|---|---|
| Assinatura | toggle() => Promise<void> |
| Parâmetros | --- |
CSS Shadow Parts
| Nome | Descrição |
|---|---|
"content" | Área de conteúdo expansível. |
"details" | Elemento details nativo do collapse. |
"trigger" | Acionador (summary) do collapse. |
Evento nativo
Elemento HTML de referência
br-collapse encapsula <details>/<summary> e expõe open no host.
Como ouvir o evento
const collapse = document.querySelector('br-collapse');
collapse.addEventListener('toggle', () => console.log(collapse.open));
Eventos nativos suportados
| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
|---|---|---|---|---|---|---|
toggle | open muda | Não | Não | Não | Sim | ToggleEvent sintético preserva oldState/newState. |
| click e teclado | <summary> é ativado | conforme o tipo | Sim | conforme o tipo | Sim | Preservados pelo <summary> interno. |
Eventos não aplicáveis ou não suportados
Eventos de formulário e valor não se aplicam. Delegação de toggle não funciona porque o evento nativo não faz bubbling.
Eventos customizados
brDidOpen/brDidClose são legados; brCollapseOpen/brCollapseClose são canônicos. Cada par ocorre uma vez antes do toggle público. Métodos legados preservam emissão imediata e suprimem a duplicação causada pelo toggle interno.
Estado, frameworks e acessibilidade
Leia event.target.open. HTML e wrappers registram listener no host. Enter/Space ativam o summary e o conteúdo participa da árvore somente quando aberto.
Evidência de teste
src/shared/contracts/platform-contract.e2e.tsx cobre interação real, ordem, flags, target e ausência de duplicação em Chromium headless.
Atributos nativos
br-collapse renderiza <details> e <summary> no Shadow DOM. A propriedade open representa o estado
expandido e é refletida no host. Use accordion-group para permitir que apenas um componente do mesmo
grupo permaneça aberto.
O atributo nativo name de <details> não é encaminhado ao elemento interno, pois o agrupamento é feito
por accordion-group. Atributos globais e ARIA continuam disponíveis no host.
Dependências
Usado por
Depende de
Gráfico
Migração de <br-collapse> (1.x → 2.x)
A propriedade collapsed da 1.x indicava o estado inverso do estado atual. Na 2.x, use open para declarar diretamente se o conteúdo está aberto.
Propriedades e composição
| API 1.x | API 2.x | Ação na migração |
|---|---|---|
| — | accordion-group | Use para coordenar vários collapses. |
collapsed | open | Inverta o valor durante a migração. |
nameIconCollapsed | iconToHide | Renomeie conforme o ícone do estado aberto/fechado. |
nameIconNotCollapsed | iconToShow | Renomeie conforme o ícone exibido. |
showIcon | iconPosition ou conteúdo customizado | Remova a flag e configure a composição atual. |
title | slot="trigger" | Mova o título para o gatilho. |
Use os eventos brCollapseOpen e brCollapseClose para acompanhar a mudança.
Exemplo
1.x:
<br-collapse collapsed title="Detalhes">Conteúdo</br-collapse>
2.x:
<br-collapse>
<span slot="trigger">Detalhes</span>
Conteúdo
</br-collapse>
