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

Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.

Apresenta e permite interagir com dados tabulares; não deve ser usada para organizar layout ou conteúdo que não seja tabular. Recebe o cabeçalho e o corpo pelos slots header e body, compostos por br-table-header e br-table-header-cell, e por br-table-body, br-table-row e br-table-cell. Orquestra a grade, a acessibilidade, a ordenação, a seleção e a expansão das linhas. A barra de ações é gerenciada pela tabela; br-table-footer é renderizado quando a paginação está habilitada. As propriedades de célula seguem, quando aplicável, a precedência: célula, linha, coluna, tabela e valor padrão.

Migração dos eventos de paginação e ordenação

Os eventos brTableFooterPageChange e brTableFooterPerPageChange foram removidos de br-table-footer, peça interna gerenciada pela tabela. Escute brTablePageChange e brTablePageSizeChange em br-table:

table.addEventListener('brTablePageChange', ({ detail }) => {
  carregarPagina(detail.page);
});
table.addEventListener('brTablePageSizeChange', ({ detail }) => {
  carregarPagina(1, detail.pageSize);
});

Na troca de tamanho, o payload público usa pageSize, não perPage. Os bindings correspondentes dos wrappers Angular, React e Vue seguem os eventos da tabela, não os do rodapé.

br-table-header-cell não emite mais brTableSortRequest. Escute esse evento somente em br-table: o payload continua sendo TableSortRequestDetail e preventDefault() continua cancelando a mudança local antes de brTableSortChange. Listeners de captura também recebem apenas uma solicitação pública por interação.

A comunicação entre essas peças e a tabela usa eventos brInternalTable.... Eles não são API de consumo. Os eventos internos do rodapé não propagam nem atravessam Shadow DOM. O evento interno do cabeçalho projetado pode ser observado em captura no mesmo root, mas tem nome distinto e não é cancelável.

Exemplo(s)

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

Ordenação no cabeçalho

Nas colunas com sortable, os ícones de ordenação e a cor de destaque do texto aparecem somente enquanto o ponteiro está sobre a célula do cabeçalho. Fora do hover, a célula mantém a cor de um cabeçalho sem ordenação e oculta os ícones, inclusive quando já existe uma ordenação ativa.

Esse comportamento é apenas visual: a ordenação permanece aplicada. O acionador mantém o foco visível por teclado e o nome acessível que informa o estado atual e a próxima ação de ordenação.

Divisores de linhas e colunas

Use column-divider para habilitar divisores entre colunas e row-divider para habilitar divisores entre linhas:

<br-table column-divider row-divider>
  <!-- Insira o cabeçalho e o corpo da tabela nos respectivos slots. -->
</br-table>

As propriedades JavaScript correspondentes são columnDivider e rowDivider. Sem configuração, os divisores ficam desabilitados.

Compatibilidade

Os aliases depreciados has-column-divider (hasColumnDivider) e has-row-divider (hasRowDivider) continuam funcionando. Para novos usos, prefira column-divider e row-divider.

Quando as duas formas são informadas, columnDivider e rowDivider têm precedência sobre os respectivos aliases, inclusive com false explícito (column-divider="false" ou row-divider="false" em HTML). Quando a propriedade canônica é undefined, o valor do alias é utilizado.

Densidade hierárquica

A tabela coordena a densidade das células e de suas ações. O token CSS --br-table-density é herdado: um valor definido na célula prevalece sobre o da linha, que prevalece sobre o da tabela. Alterações de style ou class nessa composição atualizam as ações sem exigir uma mudança de seleção.

Os valores de padding 8px, 16px e 24px correspondem, respectivamente, às densidades small, medium e large dos botões de ação. Células e barras usadas fora de br-table mantêm a resolução local de densidade.

Superfície dos menus de ações

Os menus de ações agrupadas das células e das barras de título e contextual usam o token semântico --background no painel e na lista de ações. Ao personalizar o tema, defina uma superfície opaca nesse token e mantenha contraste com o texto dos itens. Essa configuração é local à composição da tabela e não altera o fundo padrão de outros br-dropdown.

Os itens desses menus usam densidade small, independentemente da densidade da tabela. São ações, não opções selecionáveis: clicar nesses itens não aplica estado selecionado.

Tooltips de conteúdo

Com tooltip-mode="enabled", as células de dados e de cabeçalho exibem o texto completo ao passar o ponteiro somente quando o conteúdo excede a largura disponível. Se o texto couber inteiro, inclusive com overflow="wrap", o tooltip não aparece. Com tooltip-mode="disabled", ele permanece desabilitado mesmo quando há truncamento.

Nas células de dados, a configuração local tem precedência sobre a linha, a coluna e a tabela, nessa ordem. O tooltip das ações agrupadas continua independente dessa verificação de truncamento.

Para configurar o tooltip das ações agrupadas nas células, use more-actions-label (moreActionsLabel em JavaScript) em br-table-cell ou em br-table:

<br-table more-actions-label="Ações da tabela">
  <br-table-body slot="body">
    <br-table-row>
      <br-table-cell cell-actions-limit="1" more-actions-label="Ações deste registro">
        <br-table-action label="Editar"></br-table-action>
        <br-table-action label="Excluir"></br-table-action>
      </br-table-cell>
    </br-table-row>
  </br-table-body>
</br-table>

Quando as duas propriedades são informadas, a da tabela prevalece sobre a da célula. Se a tabela não definir a propriedade, cada célula usa seu próprio valor. O fallback, inclusive para valores vazios ou compostos apenas por espaços, é “Mais ações”. O texto é literal e não altera o nome acessível do botão ou os rótulos do menu.

As barras de título e contextual também têm propriedades independentes: more-actions-heading-label e more-actions-contextual-label. Configure-as em br-table; a barra interna aplica “Mais ações” quando os valores são vazios ou compostos apenas por espaços:

<br-table
  heading="Clientes"
  heading-actions-limit="1"
  contextual-actions-limit="1"
  show-contextual-bar
  more-actions-heading-label="Ações gerais"
  more-actions-contextual-label="Ações selecionadas"
>
  <br-table-action slot="global-actions" label="Exportar"></br-table-action>
  <br-table-action slot="global-actions" label="Imprimir"></br-table-action>
  <br-table-action slot="contextual-actions" label="Editar"></br-table-action>
  <br-table-action slot="contextual-actions" label="Excluir"></br-table-action>
</br-table>

Essas configurações da barra não alteram os nomes acessíveis dos botões nem os rótulos dos menus.

Busca controlada pela aplicação

Use has-search (hasSearch no JavaScript) para disponibilizar a interface de busca. Por padrão, ela não é exibida. A tabela não filtra linhas nem destaca texto automaticamente.

Ao pressionar Enter no campo ou acionar o botão de envio, a barra emite brTableSearch com detail: { term }. O evento propaga até br-table e atravessa Shadow DOM (bubbles: true, composed: true, cancelable: true). Digitar, inicializar ou alterar propriedades programaticamente não solicita uma busca. Enter durante composição de texto não envia a busca.

Fechar a busca limpa o campo, emite { term: '' } e devolve o foco ao botão de abertura. Desabilitar hasSearch oculta e limpa a interface sem emitir o evento.

<br-table has-search>
  <!-- Forneça o cabeçalho e as linhas nos respectivos slots. -->
</br-table>

A aplicação deve escutar brTableSearch na tabela e filtrar seus dados locais ou consultar um serviço. Depois, deve fornecer os resultados por setData() ou atualizar os slots. Campos pesquisáveis, inclusão do conteúdo expandido, destaques, tratamento de erros, concorrência e paginação são definidos pela aplicação. A solicitação de busca não altera a página atual automaticamente.

Rolagem virtual e cabeçalho fixo

A lista virtual reutiliza a altura medida do cabeçalho fixo durante a rolagem. Mudanças de tamanho por densidade, largura ou conteúdo atualizam essa medida automaticamente com ResizeObserver, sem reiniciar a lista nem voltar ao topo. Em ambientes sem essa API, a medida é atualizada na montagem e nas invalidações de densidade e estrutura; mudanças apenas de CSS externo podem exigir uma nova montagem.

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.

O indicador acompanha a área visível dos dados, mesmo com rolagem e virtualização, sem cobrir a barra de ações ou o rodapé. Alternar loading não reinicia a rolagem nem altera seleção, expansão ou página. O estado intercepta o ponteiro sobre os dados, mas não move o foco nem bloqueia o teclado.

Use ::part(loading) para estilizar a área do indicador e --br-table-loading-opacity para ajustar a opacidade dos dados durante o carregamento (padrão 0.5). O slot loading substitui o indicador padrão br-loading, cujo rótulo é “Carregando dados”.

Contrato de interação por teclado

Decisão e escopo

br-table adota o padrão Grid do WAI-ARIA Authoring Practices Guide (APG) para navegação por teclado. A grade compreende o cabeçalho e as células de dados; barra de ações e rodapé permanecem fora dela e mantêm a ordem de foco normal da página.

Este é o contrato de navegação por teclado e gerenciamento de foco da br-table.

O contêiner dos dados usa role="grid", com role="row" nas linhas, role="columnheader" nos cabeçalhos e role="gridcell" nas células de dados. A barra de ações e o rodapé não fazem parte da grade.

O APG define o grid como um widget composto: somente um ponto da grade participa da sequência de Tab, e o componente é responsável por mover o foco entre suas células. Para controles dentro das células, este contrato adota os modos de navegação e interação a seguir.

Sequência de Tab e foco

• Tab leva o foco para a célula ativa anteriormente ou, na primeira entrada, para a primeira célula focalizável da grade.
• Shift+Tab e Tab, quando usados no modo de navegação, saem da grade para o elemento focalizável anterior ou seguinte da página. Eles não percorrem todas as células nem cada controle interno.
• A grade mantém uma única célula ativa por vez. O foco visível deve acompanhar a célula ativa durante a navegação.
• A navegação sempre foca a superfície da célula, inclusive quando ela contém um único controle. O controle só recebe foco ao entrar no modo de interação.
• Cabeçalhos sem ações não precisam ser focalizáveis. Células de dados devem poder receber foco ou conter um elemento focalizável, inclusive quando seu conteúdo for somente leitura.

Navegação entre células

As teclas abaixo movem o foco no modo de navegação. Quando o foco chega à primeira ou à última célula no sentido solicitado, ele permanece nela; a navegação não dá a volta para o lado oposto.

Tecla	Comportamento
Seta para a direita / Seta para a esquerda	Move uma célula na linha atual.
Seta para baixo / Seta para cima	Move uma célula na coluna atual.
Home / End	Move para a primeira / última célula da linha atual.
Ctrl+Home / Ctrl+End	Move para a primeira célula da grade / última célula da grade.
Page Down / Page Up	Move a quantidade de linhas definida por visibleRows, preservando a coluna quando possível e acompanhando a rolagem.

O salto de Page Down/Page Up usa o valor efetivo de visibleRows: valores fracionários são arredondados para baixo e limitados ao intervalo de 1 a 50; valores não finitos usam 10. pageSize não define esse deslocamento. O cabeçalho participa da navegação como a primeira linha da grade. Por exemplo, com visibleRows="3", Page Down na primeira linha de dados alcança a quarta linha de dados, na mesma coluna. Se faltarem linhas para completar o salto, o foco para na primeira ou última linha, sem mudar de coluna em uma grade retangular. O movimento não troca a página de dados; ele permanece na grade da página atual.

Virtualização e dados remotos

O destino é calculado nas linhas lógicas da página atual, não apenas nas linhas montadas no DOM. Se necessário, a tabela atualiza a janela virtual e a rolagem, aguarda a renderização e move o foco para a célula de destino. Durante essa transição, a grade mantém o foco e considera o destino pendente ao receber novas teclas de navegação. A célula fica visível sem ser encoberta pelo cabeçalho.

Com paginação local, Ctrl+End alcança a última célula da página atual. Com paginação por API, alcança a última célula do subconjunto atualmente fornecido pelo consumidor, mesmo que totalItems informe um total maior. O total não materializa linhas ausentes e não transforma esse atalho em uma busca pela última linha global.

Ctrl+End, setas e Page Down/Page Up não alteram currentPage, não emitem brTablePageChange nem solicitam dados remotos. Para alcançar outra página, use a paginação do rodapé; a aplicação continua responsável por obter e fornecer os dados. Enquanto loading preserva os dados anteriores, a navegação permanece limitada a eles.

Entrar e sair dos controles de uma célula

• Enter ou F2, com uma célula ativa que contenha controles, entra no modo de interação e move o foco para o primeiro controle habilitado e visível da célula, na ordem do DOM. A entrada não ativa o controle.
• Se a célula não contiver controles focalizáveis, Enter e F2 não mudam o foco nem o modo.
• No modo de interação, os controles mantêm seu comportamento nativo. Setas, Enter, Space e outras teclas são interpretadas pelo controle focado, não pela navegação da grade.
• Tab e Shift+Tab percorrem os controles da célula atual. Depois do último ou antes do primeiro controle, respectivamente, o foco sai da grade para o próximo ou o anterior elemento focalizável da página. O foco não fica preso na célula.
• Escape ou F2 retorna o foco à célula que contém o controle e reativa o modo de navegação. Se Escape estiver sendo usado pelo controle para fechar um pop-up ou executar outra ação local, essa ação ocorre primeiro; uma nova pressão pode sair do modo de interação.

Controles nativos e componentes com delegação de foco, como br-button, br-checkbox e br-table-action, mantêm o foco no controle durante a interação. Controles customizados devem delegar o foco ao elemento interno e respeitar tabindex no host. Não use valores positivos de tabindex nas células. Um controle com tabindex="-1" explícito não participa da navegação por teclado da célula.

Testes automatizados e anúncios por leitor de tela

Os testes automatizados verificam papéis, nomes acessíveis, contagens e índices ARIA, destino do foco e teclas, inclusive quando uma linha virtualizada é materializada. Essas verificações inspecionam a árvore de acessibilidade exposta ao navegador; não observam nem comprovam a fala, sua ordem ou a repetição dos anúncios produzidos por um leitor de tela. Esse resultado também depende do leitor, navegador, sistema operacional e configurações de anúncio.

Para confirmar a fala, valide manualmente a navegação em uma combinação real de leitor de tela, navegador e sistema operacional. Registre essa combinação, as configurações de anúncio de cabeçalhos e coordenadas e os resultados observados. Não descreva a aprovação dos testes automatizados como validação dos anúncios por voz.

Referência

• Grid Pattern — WAI-ARIA APG: sequência de Tab, gerenciamento de foco e teclas de navegação para data grids.

Leitores de tela

Para leitores de tela, a tabela expõe uma grade nomeada, papéis e índices lógicos para cabeçalhos e células. O conteúdo da célula compõe seu nome acessível, mas o componente não associa automaticamente o texto do cabeçalho à célula. Os testes verificam semântica e foco, não a fala: a repetição de cabeçalhos, coordenadas e a forma dos anúncios dependem do leitor, navegador e configurações.

Conteúdo longo

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

cellActionsLimit

Atributo	cell-actions-limit
Descrição	Limite padrão de ações exibidas em cada célula.
Tipo	number
Valor padrão	4

columnDivider

Atributo	column-divider
Descrição	Habilita divisores entre colunas.
Observações	Quando informado, tem precedência sobre hasColumnDivider, inclusive quando false. Na ausência de ambos, os divisores ficam desabilitados.
Tipo	boolean
Valor padrão	---

columnWidth

Atributo	column-width
Descrição	Largura padrão utilizada pelas colunas sem configuração própria.
Tipo	"content" | "fill" | `${number}fr` | `${number}px`
Valor padrão	---

contextualActionsLimit

Atributo	contextual-actions-limit
Descrição	Limite usado para decidir quando agrupar ações contextuais em um menu. Quando o número de ações excede esse valor, as ações são agrupadas no dropdown (atualmente todas são movidas para o menu colapsado).
Tipo	number
Valor padrão	4

currentPage

Atributo	current-page
Descrição	Página atual exibida pela paginação (1-indexada).
Observações	Atualizada internamente quando TableDataStore já cobre a página solicitada. Utilize como valor inicial ou para navegar programaticamente para outra página.
Tipo	number
Valor padrão	1

density

Atributo	density
Descrição	Densidade visual aplicada aos espaçamentos da tabela.
Observações	Quando omitida, a propriedade permanece undefined e a densidade visual média é aplicada aos tokens da tabela.
Tipo	"large" | "medium" | "small"
Valor padrão	---

dividerStyle

Atributo	divider-style
Descrição	Estilo aplicado aos divisores habilitados.
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 instead.
Descrição	Habilita divisores entre colunas quando columnDivider não é informado.
Tipo	boolean
Valor padrão	false

hasPagination

Atributo	has-pagination
Descrição	Habilita a paginação da tabela, renderizando br-table-footer internamente.
Observações	A paginação define o subconjunto lógico disponível para a lista virtual. pageSize controla quantas linhas pertencem à página e visibleRows controla quantas delas cabem simultaneamente na viewport. Quando os dados completos ainda não estão disponíveis localmente (paginação por API), informe totalItems e forneça o subconjunto correspondente após brTablePageChange.
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 instead.
Descrição	Habilita divisores entre linhas quando rowDivider não é informado.
Tipo	boolean
Valor padrão	false

hasRowExpansion

Atributo	has-row-expansion
Descrição	Habilita a coluna de expansão de linhas.
Tipo	boolean
Valor padrão	false

hasRowHover

Atributo	has-row-hover
Descrição	Habilita o realce visual das linhas ao passar o ponteiro.
Tipo	boolean
Valor padrão	false

hasRowSelection

Atributo	has-row-selection
Descrição	Habilita a coluna de seleção de linhas.
Tipo	boolean
Valor padrão	false

hasSearch

Atributo	has-search
Descrição	Disponibiliza a interface de busca, sem filtrar ou destacar o conteúdo. A aplicação recebe brTableSearch e atualiza os dados local ou remotamente.
Tipo	boolean
Valor padrão	false

heading

Atributo	heading
Descrição	Título apresentado na barra principal.
Tipo	string
Valor padrão	---

headingActionsLimit

Atributo	heading-actions-limit
Descrição	Limite usado para decidir quando agrupar ações globais em um menu. Quando o número de ações excede esse valor, as ações são agrupadas no dropdown (atualmente todas são movidas para o menu colapsado).
Tipo	number
Valor padrão	4

horizontalAlignment

Atributo	horizontal-alignment
Descrição	Alinhamento horizontal padrão da tabela.
Tipo	"center" | "end" | "start"
Valor padrão	---

loading

Atributo	loading
Descrição	Indica que as linhas estão sendo atualizadas pelo consumidor.
Observações	Mantém os dados anteriores, reduz sua opacidade e exibe o slot loading sobre a viewport, sem cobrir a barra de ações ou o rodapé. Reflete o atributo loading e pode ser alterada diretamente ou pelos métodos startLoading() e stopLoading(). Não bloqueia o teclado nem gerencia requisições, erros ou substituição dos dados.
Tipo	boolean
Valor padrão	false

moreActionsContextualLabel

Atributo	more-actions-contextual-label
Descrição	Texto do tooltip do botão de ações agrupadas da barra contextual. Quando vazio ou composto apenas por espaços, usa "Mais ações". Não altera o nome acessível do botão nem os rótulos do menu.
Tipo	string
Valor padrão	'Mais ações'

moreActionsHeadingLabel

Atributo	more-actions-heading-label
Descrição	Texto do tooltip do botão de ações agrupadas na barra de título. Quando vazio ou composto apenas por espaços, usa "Mais ações". Não altera o nome acessível do botão nem os rótulos do menu.
Tipo	string
Valor padrão	'Mais ações'

moreActionsLabel

Atributo	more-actions-label
Descrição	Texto completo do tooltip dos botões de ações agrupadas nas células. Quando informado, prevalece sobre moreActionsLabel de cada célula. Quando omitido, a célula usa seu valor local ou "Mais ações". Valores vazios ou compostos apenas por espaços usam "Mais ações". Aceita texto simples por atributo ou propriedade. Reflete o valor no atributo more-actions-label para sincronizar as células.
Tipo	string
Valor padrão	---

overflow

Atributo	overflow
Descrição	Estratégia padrão para conteúdos que excedem a célula.
Tipo	"truncate" | "wrap"
Valor padrão	'wrap'

pageSize

Atributo	page-size
Descrição	Quantidade de linhas pertencentes a cada página.
Observações	Quando omitida, utiliza visibleRows como fallback para manter compatibilidade com a API anterior. Defina um valor maior que visibleRows para que paginação e virtualização operem simultaneamente.
Tipo	number
Valor padrão	---

pageSizeOptions

Atributo	---
Descrição	Opções disponíveis de itens por página no seletor da paginação.
Tipo	number[]
Valor padrão	[10, 20, 30]

rowDivider

Atributo	row-divider
Descrição	Habilita divisores entre linhas.
Observações	Quando informado, tem precedência sobre hasRowDivider, inclusive quando false. Na ausência de ambos, os divisores ficam desabilitados.
Tipo	boolean
Valor padrão	---

showContextualBar

Atributo	show-contextual-bar
Descrição	Força a apresentação da barra contextual.
Tipo	boolean
Valor padrão	false

sortMode

Atributo	sort-mode
Descrição	Define se a tabela aceita uma única coluna ordenada ou múltiplas colunas. No modo multi, a prioridade é sempre a ordem visual da esquerda para a direita.
Tipo	"multi" | "single"
Valor padrão	'single'

tooltipMode

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

tooltipState

Atributo	tooltip-state
Descrição	Estado visual padrão dos tooltips.
Tipo	"danger" | "info" | "success" | "warning"
Valor padrão	'info'

totalItems

Atributo	total-items
Descrição	Quantidade total de itens do conjunto de dados.
Observações	Necessário apenas quando TableDataStore não contém o conjunto completo (paginação por API). Quando omitido, é derivado automaticamente da quantidade de linhas já presentes na tabela.
Tipo	number
Valor padrão	---

verticalAlignment

Atributo	vertical-alignment
Descrição	Alinhamento vertical padrão da tabela.
Tipo	"center" | "end" | "start"
Valor padrão	---

virtualExpandedContentHeight

Atributo	virtual-expanded-content-height
Descrição	Altura adicional estimada para conteúdo expandido ainda não medido.
Tipo	number
Valor padrão	240

visibleRows

Atributo	visible-rows
Descrição	Quantidade de linhas de dados visíveis simultaneamente na viewport.
Observações	Não limita o conjunto de dados nem realiza paginação. A altura da região de scroll é derivada desta quantidade e da densidade atual. Mesmo com hasPagination habilitado, esta propriedade continua definindo apenas a capacidade visual da viewport; pageSize define o tamanho lógico da página.
Tipo	number
Valor padrão	10

Slots

Nome	Descrição
"body"	Componente br-table-body que contém as linhas de dados.
"contextual-actions"	Ações aplicadas às linhas selecionadas.
"global-actions"	Ações aplicadas ao conjunto completo de dados.
"header"	Componente br-table-header que define as colunas.
"loading"	Indicador exibido enquanto as linhas são atualizadas.

Eventos

Evento	Descrição	Depreciação	Propagação
brTableActionClick	Reemite ações globais, contextuais e de linha para o consumidor.	---	true
brTablePageChange	Emitido quando o consumidor solicita outra página pela paginação do rodapé.	---	true
brTablePageSizeChange	Emitido quando o consumidor solicita outra quantidade de itens por página; atualize visibleRows ao tratar.	---	true
brTableRowExpansionChange	Emitido quando uma linha é expandida ou recolhida.	---	true
brTableSearch	Evento customizado originado em br-table-bar e propagado pela tabela, sem reemissão. Envia { term } por Enter ou botão e { term: '' } ao fechar. Digitação, inicialização e alterações programáticas não emitem o evento. Propaga, atravessa Shadow DOM e é cancelável.	---	true
brTableSelectionChange	Emitido quando o conjunto de linhas selecionadas muda.	---	true
brTableSortChange	Emitido sempre que o conjunto de critérios de ordenação muda.	---	true
brTableSortRequest	Emitido antes de aplicar uma solicitação de ordenação; preventDefault() cancela a mudança local.	---	true

Métodos

clearSelection

Descrição	Limpa a seleção de todas as linhas elegíveis.
Assinatura	clearSelection() => Promise<void>
Parâmetros	---

collapseAllRows

Descrição	Recolhe todas as linhas que estiverem expandidas.
Assinatura	collapseAllRows() => Promise<void>
Parâmetros	---

collapseRow

Descrição	Recolhe uma linha do corpo.
Assinatura	collapseRow(rowIndex: number) => Promise<void>
Parâmetros	rowIndex: Índice da linha, começando em zero.

expandRow

Descrição	Expande uma linha elegível do corpo.
Assinatura	expandRow(rowIndex: number) => Promise<void>
Parâmetros	rowIndex: Índice da linha, começando em zero.

getSelectedRows

Descrição	Retorna as linhas atualmente selecionadas.
Assinatura	getSelectedRows() => Promise<HTMLBrTableRowElement[]>
Parâmetros	---

getSorting

Descrição	Retorna o estado atual de ordenação aplicado na tabela.
Assinatura	getSorting() => Promise<TableSortState[]>
Parâmetros	---

selectAllRows

Descrição	Seleciona todas as linhas elegíveis.
Assinatura	selectAllRows() => Promise<void>
Parâmetros	---

setData

Descrição	Substitui os dados lógicos da tabela e reconstrói seus subcomponentes.
Assinatura	setData(data: TableData) => Promise<void>
Parâmetros	data: Colunas, linhas e ações que formarão a tabela.

startLoading

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

stopLoading

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

CSS Shadow Parts

Nome	Descrição
"container"	Contêiner visual principal.
"content"	Grid que contém cabeçalho e corpo.
"footer"	Contêiner do rodapé, exibido abaixo do corpo da tabela.
"loading"	Área do indicador de carregamento sobre a viewport dos dados.
"scroll-container"	Área com rolagem que contém apenas os dados da tabela.

Acessibilidade

O br-table usa o padrão ARIA grid mesmo com layout em CSS Grid: o contêiner interno que envolve apenas o cabeçalho e o corpo tem role="grid" (isolado da barra de ações e do rodapé, que não são filhos válidos desse papel) e os subcomponentes fornecem role="row", role="columnheader" e role="gridcell", organizados em rowgroup. O componente calcula e aplica aria-colcount/aria-rowcount somente nesse contêiner, aria-rowindex nas linhas e aria-colindex nas células. Para consultar contagens, use o elemento com role="grid" no Shadow DOM, não o host br-table. As colunas auxiliares de expansão e seleção também usam columnheader e gridcell; seus índices refletem a ordem visual (expansão, seleção e dados) e são incluídos em aria-colcount. A estrutura de linhas e colunas associa as células aos cabeçalhos, sem aplicar aria-labelledby automaticamente às células. Referenciar somente o cabeçalho nesse atributo substituiria o valor no nome acessível: “Maria” passaria a ser nomeada apenas como “Nome”. Rótulos explícitos do consumidor são preservados; prefira o conteúdo da célula para não ocultar dados ou controles na leitura.

Nome da grade

O nome é aplicado ao grid interno como texto em aria-label. Na configuração do host, aria-labelledby tem precedência sobre aria-label: os textos dos elementos referenciados são concatenados na ordem dos IDs, no mesmo documento ou Shadow DOM que contém br-table. Use referências a rótulos textuais; essa resolução não implementa todo o algoritmo de nome acessível para controles ou conteúdo não textual. IDs inexistentes são ignorados. Sem texto resolvido, o componente usa aria-label, depois heading e, por último, “Tabela”. Os atributos explícitos do consumidor são preservados; o componente não injeta rótulo oculto nem aria-labelledby no host.

Seleção

Com has-row-selection, o grid expõe aria-multiselectable="true" e as linhas de dados recebem aria-selected="true" ou "false" conforme o estado. A linha de cabeçalho não recebe aria-selected. Sem seleção habilitada, esses atributos são omitidos; o estado lógico selected/data-selected é preservado para quando a seleção for habilitada novamente.

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 contexto 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 no contêiner com role="grid" e expõe um role="status" com aria-live="polite" associado à atualização. O indicador fica sobre a área visível dos dados, fora da árvore de linhas, e intercepta o ponteiro nessa área. A barra de ações e o rodapé não são cobertos. O carregamento não move o foco nem bloqueia a navegação por teclado. Esses atributos expõem o estado ao leitor de tela; a mensagem e o momento de um eventual anúncio dependem do navegador, do leitor e de suas configurações.

Teclado e foco

A grade mantém somente uma célula na sequência global de Tab. Tab entra na célula ativa anteriormente (ou na primeira célula na entrada inicial); Tab e Shift+Tab saem da grade no modo de navegação. Cabeçalho e dados participam da navegação, mas a barra de ações e o rodapé mantêm a sequência normal da página.

As setas movem o foco entre células sem dar a volta. Home e End vão aos extremos da linha; Ctrl+Home e Ctrl+End vão aos extremos da grade. Page Up e Page Down movem visibleRows linhas, preservando a coluna e acompanhando a rolagem, inclusive quando o destino precisa ser materializado pela lista virtual. Durante a renderização do destino, o foco permanece na tabela e novas teclas de navegação partem da célula pendente. Com paginação, a navegação permanece na página atual: Ctrl+End alcança a última célula das linhas fornecidas, não a última linha global indicada por totalItems quando os dados vêm de uma API. Esses atalhos não solicitam dados nem emitem brTablePageChange; a troca de página continua sendo feita pelo rodapé e tratada pela aplicação consumidora.

Os menus de ações das barras e células fecham assim que a área de dados começa a rolar, tanto na vertical quanto na horizontal. Rolar a lista interna de um menu não o fecha. O fechamento não reposiciona a rolagem da tabela. O tooltip de um trigger fica oculto enquanto seu menu está aberto e ao fechar o menu; uma nova interação de hover ou foco volta a exibir a dica.

O foco visível acompanha a superfície da célula, inclusive quando contém somente texto ou um único controle. Enter ou F2 entra no primeiro controle habilitado e visível sem ativá-lo. Dentro da célula, os controles preservam seu teclado nativo; Tab e Shift+Tab percorrem seus controles e saem da grade nas extremidades. Escape ou F2 retorna à célula; Escape já consumido por um controle tem precedência.

Ao expandir ou recolher uma linha, as linhas que permanecem na janela virtual não são desmontadas. Isso preserva o foco e o hover durante a atualização.

Controles customizados devem delegar foco e respeitar tabindex no host. Valores positivos de tabindex não devem ser usados. Controles declarados com tabindex="-1" permanecem fora da navegação por teclado da célula.

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.

Leitores de tela

A estrutura de acessibilidade expõe uma grade nomeada, linhas, cabeçalhos de coluna e células de dados com nomes acessíveis e índices lógicos. O cabeçalho ocupa a linha 1; a primeira linha de dados ocupa a linha 2. Com paginação, os índices refletem a posição no conjunto completo. Na paginação por API, a tabela soma o deslocamento de currentPage e pageSize aos índices das linhas recebidas; aria-rowcount inclui totalItems e o cabeçalho. As células mantêm seu próprio conteúdo como nome acessível, mas não são associadas automaticamente ao texto do cabeçalho por aria-labelledby. Use cabeçalhos com texto significativo e não dependa de o leitor repetir o cabeçalho ou as coordenadas ao mover o foco.

Os testes automatizados verificam a árvore de acessibilidade (nome da grade, papéis, contagens, índices e nomes de células e controles) e o foco durante a navegação por teclado. Eles não verificam fala, ordem ou repetição de anúncios, nem comprovam como um leitor associa o cabeçalho à célula. A forma exata de apresentação depende do leitor, navegador, sistema operacional e configurações. Não descreva os testes automatizados como validação de anúncios por voz; registre separadamente os resultados de qualquer teste manual com leitor de tela.

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-action
• br-table-bar
• br-table-body
• br-table-cell
• br-table-footer
• br-table-header
• br-table-header-cell
• br-table-row

Depende de

• br-table-bar
• br-loading
• br-table-footer
• br-table-action
• br-table-cell
• br-table-header-cell
• br-table-row
• br-checkbox

Gráfico