Collapse

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

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)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Padrão

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

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 do ícone exibido quando o conteúdo está visível. O valor padrão usa o registro SVG local.
Tipo	string
Valor padrão	'fa6-solid:chevron-up'

iconToShow

Atributo	icon-to-show
Descrição	Identificador do ícone exibido quando o conteúdo está oculto. O valor padrão usa o registro SVG local.
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.
"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 Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.		Use brCollapseClose.	true
brDidOpen Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.		Use brCollapseOpen.	true

Métodos

closeCollapse Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Descrição	Fecha o collapse programaticamente.
Assinatura	closeCollapse() => Promise<void>
Depreciação	Atualize a propriedade open.
Parâmetros	---

openCollapse Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

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

• br-list

Depende de

• br-icon

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>