Table

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-table é o elemento oficial do GovBR-DS para exibição e gerenciamento de dados tabulares estruturados em linhas e colunas, desenvolvido com suporte a CSS Grid, responsividade e alta flexibilidade de composição.

Para que serve

• Apresentação de conjuntos de dados relacionais: Organiza registros com múltiplos atributos comparáveis (ex.: relatórios, tabelas de processos, listagens financeiras).
• Recursos interativos avançados: Suporta ordenação por coluna, seleção simples ou múltipla de linhas, densidades variadas (alta, média, baixa) e paginação integrada com br-pagination.
• Acessibilidade WAI-ARIA: Preserva a semântica de tabela acessível (role="table", role="columnheader", role="row", role="cell") mesmo em leiautes baseados em CSS Grid.

Quando utilizar

• Utilize quando:
  • As informações compartilharem campos e atributos fixos que justifiquem a comparação lado a lado em colunas.
  • A pessoa usuária precisar ordenar, filtrar ou selecionar múltiplos registros da lista.
• Evite e prefira outro componente quando:
  • Os itens forem heterogêneos com estruturas visuais distintas (prefira br-card).
  • Houver apenas um texto linear simples por item (prefira br-list).

Composição e Subcomponentes

O ecossistema da Tabela segue a hierarquia semântica modular:

Subcomponente	Papel	Regra de uso
br-table-body	Corpo de dados. Agrupa as linhas de registros de conteúdo.	Declarado no slot body (ou padrão) da tabela.
br-table-cell	Célula de dados. Célula de conteúdo individual de uma coluna.	Declarado dentro de br-table-row no corpo de dados.
br-table-header-cell	Célula de título. Célula de cabeçalho com suporte a botão de ordenação.	Declarado dentro de br-table-row no cabeçalho.
br-table-header	Seção de cabeçalho. Agrupa as linhas de títulos das colunas.	Declarado no slot header da tabela.
br-table-row	Linha. Representa uma linha de cabeçalho ou de registro de dados.	Declarado dentro de br-table-header ou br-table-body.
br-table	Orquestrador principal. Gerencia o grid de colunas, ordenação, seleção de linhas e densidade.	Contêiner raiz da tabela.

Como os subcomponentes se relacionam

A arquitetura de br-table reflete a semântica nativa de tabelas HTML de forma modular: br-table → br-table-header / br-table-body → br-table-row → br-table-header-cell / br-table-cell. O componente pai orquestra o alinhamento das colunas via tokens de Grid, distribuindo automaticamente os estados de seleção e foco para as linhas filhas.

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ãoCarregando

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

Dados remotos

Defina loading enquanto a aplicação atualiza as linhas. O componente mantém o conteúdo anterior com opacidade reduzida, aplica aria-busy="true" e exibe o indicador customizado no slot loading, centralizado sobre os dados. Também é possível usar startLoading() e stopLoading(). A busca, o tratamento de erro e a substituição dos slots header/body permanecem sob responsabilidade da aplicação.

Para reduzir layout e pintura de seções longas ao redor da tabela, consulte o guia de content-visibility. Essa técnica não substitui paginação ou virtualização das linhas.

Propriedades

columnDivider

Atributo	column-divider
Descrição	Ativa divisores verticais. Quando informada, tem precedência sobre hasColumnDivider.
Tipo	boolean
Valor padrão	---

columnWidth

Atributo	column-width
Descrição	Largura global aplicada a todas as colunas.
Exemplo de uso	<br-table column-width="160px"></br-table>
Observações	Valores aceitos: - fill - content - ${number}px - ${number}fr Observação: - columnWidth não define o comportamento de overflow, mas pode interferir na sua percepção ao alterar o espaço disponível da coluna. - content (max-content) tende a expandir a coluna e reduzir casos visíveis de truncagem. - fill (1fr) tende a evidenciar truncagem quando o espaço horizontal é insuficiente.
Tipo	"content" | "fill" | `${number}fr` | `${number}px`
Valor padrão	---

density

Atributo	density
Descrição	Define a densidade visual do componente. - small: Alta densidade (componente menor, mais compacto e com menos espaçamento). - medium: Densidade intermediária, padrão recomendado para a maioria dos casos. - large: Baixa densidade (componente maior, mais espaçamento e altura). Valores inválidos usam medium. Quando omitida, a densidade média é aplicada ao token.
Tipo	"large" | "medium" | "small"
Valor padrão	---

dividerStyle

Atributo	divider-style
Descrição	Define o estilo visual dos divisores.
Observações	Valores aceitos: - solid - dashed
Tipo	"dashed" | "solid"
Valor padrão	---

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

Atributo	has-column-divider
Depreciação	Use columnDivider.
Descrição	Ativa divisores verticais entre colunas.
Tipo	boolean
Valor padrão	false

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

Atributo	has-row-divider
Depreciação	Use rowDivider.
Descrição	Ativa divisores horizontais entre linhas.
Tipo	boolean
Valor padrão	false

horizontalAlignment

Atributo	horizontal-alignment
Descrição	Define o alinhamento horizontal do conteúdo das células.
Observações	Valores aceitos: - start - center - end
Tipo	"center" | "end" | "start"
Valor padrão	---

loading

Atributo	loading
Descrição	Indica que as linhas estão sendo atualizadas pelo consumidor. O componente mantém o conteúdo anterior, aplica aria-busy="true" e exibe o slot loading sobre os dados; transporte, erro e substituição das linhas ficam sob responsabilidade da aplicação. A prop pode ser alterada diretamente ou pelos métodos startLoading() e stopLoading().
Tipo	boolean
Valor padrão	false

overflow

Atributo	overflow
Descrição	Define o comportamento de overflow para as células.
Observações	Valores aceitos: - truncate - wrap Observação: - O overflow é independente de columnWidth. - Com columnWidth="content", a coluna tende a crescer com o conteúdo (max-content), o que pode reduzir casos visíveis de truncagem. - Com columnWidth="fill", a coluna ocupa o espaço disponível (1fr), então a truncagem tende a ficar mais evidente quando não há espaço suficiente.
Tipo	"truncate" | "wrap"
Valor padrão	'wrap'

rowDivider

Atributo	row-divider
Descrição	Ativa divisores horizontais. Quando informada, tem precedência sobre hasRowDivider.
Tipo	boolean
Valor padrão	---

tooltipMode

Atributo	tooltip-mode
Descrição	Define o modo de resolução do tooltip nas células da tabela.
Observações	Valores aceitos: - inherit - enabled - disabled
Tipo	"disabled" | "enabled" | "inherit"
Valor padrão	---

tooltipState

Atributo	tooltip-state
Descrição	Define o estado semântico do tooltip nas células da tabela.
Observações	Valores aceitos: - info - warning - danger - success
Tipo	"danger" | "info" | "success" | "warning"
Valor padrão	'info'

verticalAlignment

Atributo	vertical-alignment
Descrição	Define o alinhamento vertical do conteúdo das células.
Observações	Valores aceitos: - start - center - end
Tipo	"center" | "end" | "start"
Valor padrão	---

Slots

Nome	Descrição
"body"
"header"
"loading"	Indicador exibido enquanto as linhas são atualizadas.

Métodos

startLoading

Descrição	Inicia o estado de carregamento da tabela.
Assinatura	startLoading() => Promise<void>
Parâmetros	---

stopLoading

Descrição	Interrompe o estado de carregamento da tabela.
Assinatura	stopLoading() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"container"	Wrapper principal da tabela.
"content"	Área de conteúdo que contém header e body.
"loading"	Área do indicador de carregamento.

Acessibilidade

O br-table preserva a semântica de tabela mesmo com layout em CSS Grid: o host tem role="table" e os subcomponentes fornecem role="row", role="columnheader" e role="cell". O componente calcula e aplica aria-colcount/aria-rowcount, aria-rowindex, aria-colindex e associa cada célula ao seu cabeçalho de coluna via aria-labelledby.

Estrutura

• Use br-table-header + br-table-header-cell para os cabeçalhos e br-table-body + br-table-row + br-table-cell para os dados.
• Cabeçalhos de coluna devem ter texto real (não só ícone) para servirem de rótulo das células.
• Conteúdo longo respeita overflow (wrap por padrão, ou scroll); a área rolável deve ser alcançável e ter rótulo quando rolar horizontalmente.

Carregamento

Durante loading, o componente mantém o conteúdo anterior, aplica aria-busy="true" no host e expõe um role="status" com aria-live="polite" para anunciar a atualização.

Uso

O br-table é apresentação de dados tabulares — não o use para layout. Ações por linha/célula devem ser controles nativos com nome acessível.

Documentações relacionadas

Consulte o guia geral de dados remotos para atualizar linhas com loading, preservar o conteúdo anterior e tratar erros fora do componente.

Também são relacionados:

• Pagination, para navegar pelas páginas da consulta;
• Select, quando filtros da tabela usam opções remotas;
• Acessibilidade, para comunicar estados ocupados e manter a leitura da tabela.

Virtualização

Como as linhas são fornecidas via slot, a virtualização deve ser controlada pela aplicação. Renderize apenas a janela visível, preserve chaves estáveis e atualize os índices ARIA conforme a posição da linha na coleção completa. Para conjuntos extensos, prefira combinar a tabela com paginação ou com a virtualização nativa do framework utilizado pelo consumidor.

Dependências

Subcomponentes

• br-table-body
• br-table-cell
• br-table-header
• br-table-header-cell
• br-table-row

Depende de

• br-loading

Gráfico