List

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 br-list organiza coleções verticais de itens homogêneos ou relacionados, como listas de contatos, tarefas ou configurações.

Adicione os itens (como br-item) no slot padrão. Se precisar de um título ou ações no topo da lista, use o slot header ou a propriedade title.

<br-list title="Configurações">
  <br-item interactive>Notificações</br-item>
  <br-item interactive>Segurança</br-item>
</br-list>

Quando usar

• Sequências verticais de itens com leitura linear.
• Listas de opções simples ou links agrupados.

Quando evitar

• Dados em linhas e colunas com ordenação: use br-table.
• Menu lateral de navegação da página: use br-menu.

Consulte as diretrizes de design do GovBR.

Exemplos

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

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

Desempenho

Para seções extensas que permanecem no DOM, consulte o guia de content-visibility. A propriedade reduz layout e pintura fora da viewport, mas não virtualiza os itens fornecidos por slot.

Navegação por teclado

br-list organiza seus itens como um widget composto: Tab entra em um único item por vez e as setas movem o foco entre os demais. Use orientation="vertical" para listas verticais (padrão) ou orientation="horizontal" para listas horizontais.

Tecla	Comportamento
ArrowDown / ArrowUp	Na orientação vertical, move para o próximo / item anterior.
ArrowRight / ArrowLeft	Na orientação horizontal, move para o próximo / item anterior.
Enter / Space	Ativa o item com foco.
Home / End	Move para o primeiro / último item navegável.
Tab / Shift+Tab	Entra ou sai da lista; não percorre cada item individualmente.

A navegação com setas dá a volta entre o primeiro e o último item. Itens desabilitados são ignorados. Em listas aninhadas, cada lista processa somente seus próprios itens. Controles de texto mantêm suas teclas de edição; componentes como br-dropdown e br-radio também podem consumir primeiro as teclas que lhes pertencem.

Cada br-item navegável gerenciado pela lista participa da sequência interna com roving tabindex: somente o item ativo é alcançado ao entrar com Tab. Use focusFirstItem() quando a lista for aberta por um componente que precise posicionar o foco no primeiro item.

Propriedades

accordion

Atributo	accordion
Descrição	Título do grupo de accordion. br-list irmãs (mesmo elemento-pai) com o mesmo valor formam um grupo e mantêm apenas uma aberta por vez — abrir uma fecha as demais do grupo. Sozinha já torna a lista recolhível (não precisa de collapse) e, como o collapse, exige um cabeçalho (header ou slot header) como acionador. Começa recolhida.
Tipo	string
Valor padrão	null

collapse

Atributo	collapse
Descrição	Torna a lista recolhível: o corpo é envolvido por um br-collapse interno que abre e fecha ao acionar o cabeçalho. Começa recolhida. Requer um cabeçalho (atributo header ou slot header) — ele é o acionador. Sem cabeçalho não há como recolher. Para "apenas uma aberta por vez" entre listas, use accordion.
Tipo	boolean
Valor padrão	false

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()

density

Atributo	density
Descrição	Modificador de densidade da lista. Aceita small, medium ou large. Valores inválidos usam medium. Quando omitida ou null, nenhuma densidade é aplicada.
Tipo	"large" | "medium" | "small"
Valor padrão	null

divider

Atributo	divider
Descrição	Indica se a lista possui divisores (divider) entre os itens.
Tipo	boolean
Valor padrão	false

header

Atributo	header
Descrição	Define o texto do cabeçalho da lista. Quando definido, também é usado como aria-label do elemento role="list", fornecendo um nome acessível que leitores de tela anunciam ao entrar na lista.
Tipo	string
Valor padrão	null

hideHeaderDivider

Atributo	hide-header-divider
Descrição	Indica que o divider para o título da lista estará oculto.
Tipo	boolean
Valor padrão	false

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

Atributo	is-horizontal
Depreciação	Use orientation.
Descrição	Indica se a lista será horizontal. Por padrão, a lista é vertical.
Tipo	boolean
Valor padrão	false

listRole

Atributo	list-role
Descrição	Semântica do host quando o conteúdo não representa itens de lista. Valores inválidos usam list.
Tipo	"group" | "list"
Valor padrão	'list'

orientation

Atributo	orientation
Descrição	Orientação padrão. Quando informada, tem precedência sobre isHorizontal; valores inválidos usam vertical.
Tipo	"horizontal" | "vertical"
Valor padrão	---

Slots

Nome	Descrição
"default"	Slot para os itens da lista.
"header"	Slot para ações ou conteúdo do cabeçalho da lista.

Métodos

focusFirstItem

Descrição	Move o foco para o primeiro item navegável da lista. API pública para componentes que abrem a lista programaticamente (ex.: br-dropdown), evitando acesso direto ao br-item.
Assinatura	focusFirstItem() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"container"	Wrapper principal da lista.

Dependências

Usado por

• br-breadcrumb
• br-footer-category
• br-header-list
• br-pagination
• br-skip-link
• br-table-bar
• br-table-cell
• br-upload

Depende de

• br-collapse

Gráfico

Migração de <br-list> (1.x → 2.x)

A lista da 2.x usa nomes que descrevem sua estrutura e delega comportamento de recolhimento aos recursos atuais de composição.

Propriedades

API 1.x	API 2.x	Ação na migração
dataToggle / dataUnique	collapse/accordion atuais	Reestruture o comportamento usando os componentes atuais.
density	density	Mantenha.
hideTitleDivider	hideHeaderDivider	Renomeie a propriedade.
horizontal	orientation	Use orientation="horizontal" ou orientation="vertical".
spaceBetween	—	Remova; ajuste a distribuição na composição/layout.
title	header	Renomeie a propriedade.

Exemplo

1.x:

<br-list title="Serviços" horizontal hide-title-divider></br-list>

2.x:

<br-list header="Serviços" orientation="horizontal" hide-header-divider></br-list>