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 componente br-list é o contêiner estrutural do GovBR-DS desenvolvido para apresentar coleções verticais de itens homogêneos ou relacionados de forma organizada, fácil de percorrer visualmente e acessível.

Para que serve

• Apresentação sequencial de informações: Organiza listagens de dados, tarefas, configurações, opções de navegação ou mensagens.
• Cabeçalho e ações integradas: Suporta cabeçalho contextual (header) para exibição de título da lista, contadores de itens ou botões de ação em lote.
• Composição com itens padronizados: Integra-se perfeitamente com elementos br-item e divisores br-divider, mantendo ritmo visual e alinhamento consistentes.

Quando utilizar

• Utilize quando:
  • Desejar exibir uma sequência vertical de itens que compartilham a mesma estrutura ou propósito.
  • O conteúdo favorecer leitura linear ou seleção de uma linha e precisar ser percorrido visualmente com rapidez.
• Evite e prefira outro componente quando:
  • As informações forem tabulares com múltiplas colunas e necessidade de ordenação por coluna (prefira br-table).
  • A lista representar o menu principal de navegação do sistema (prefira br-menu).

Estrutura e Slots

O br-list atua como contêiner de itens:

• header: Slot opcional para cabeçalho da lista (título, filtros ou ações globais).
• default: Slot principal onde são inseridos os elementos filhos (como br-item ou divs semânticas).

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ãoItens interativosOrientação horizontalCom collapseCom Accordion

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

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.

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 canônica. 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-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>