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. Cabeçalhos multinível usam várias linhas em br-table-header com colSpan/rowSpan. Linhas contíguas com rowGroup formam unidades de ordenação, paginação e virtualização; a seleção permanece individual. Células com rowSpan não atravessam os limites do grupo. Prefira tabelas simples quando possível.

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.

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

Os textos dos cabeçalhos são azuis. Nas colunas com sortable, o estado padrão oculta o ícone; no hover ou no foco, aparece a seta dupla. Ordenada, a coluna exibe e mantém a seta para cima (crescente) ou para baixo (decrescente). O fundo de hover só aparece enquanto o ponteiro está sobre o cabeçalho. Ao remover a ordenação, a coluna volta ao estado padrão.

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.

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.

Ordenação controlada pela aplicação

Use sort-strategy="manual" quando a aplicação controlar a ordenação, por exemplo ao usar um comparador próprio ou consultar uma API. A tabela mantém o ciclo de estado dos cabeçalhos e emite brTableSortChange com detail.sorting; não altera a ordem das linhas. Ao receber os novos dados, chame setData(): o estado e os indicadores de ordenação são preservados, e a ordem enviada pela aplicação não é reordenada localmente.

O evento inclui columnIndex e direção (asc ou desc) para cada critério. O índice se refere às colunas declaradas, sem contar as colunas geradas de seleção ou expansão. sort-mode="single" (padrão) mantém um critério; sort-mode="multi" permite vários, priorizados da esquerda para a direita.

const tabela = document.querySelector('br-table');
const campos = ['nome', 'idade'];

tabela.sortStrategy = 'manual';
tabela.addEventListener('brTableSortChange', async ({ detail }) => {
  const ordenacao = detail.sorting.map(({ columnIndex, direction }) => ({
    campo: campos[columnIndex],
    direcao: direction,
  }));

  tabela.loading = true;
  try {
    await tabela.setData(await buscarRegistros({ ordenacao }));
  } finally {
    tabela.loading = false;
  }
});

Use brTableSortRequest quando precisar cancelar uma solicitação antes de a tabela atualizar seu estado, por exemplo para validar uma condição. Para ordenar externamente e manter o ciclo crescente/decrescente/padrão, prefira a estratégia manual e trate brTableSortChange.

No modo padrão, sort-strategy="local", a tabela ordena as linhas. Use sort-value para fornecer o valor de ordenação separado do texto apresentado. O sort-mode define se o estado aceita um critério (single) ou vários (multi).

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, em um painel central com scrim sobre toda a tabela, incluindo ações e paginação. 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.

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.

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, em um painel central com scrim limitado à tabela inteira. 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 scrim cobre a barra de ações, o cabeçalho, os dados e a paginação da tabela, mesmo com rolagem e virtualização. O painel tem fundo e elevação próprios e não cobre componentes vizinhos. Durante o carregamento, a tabela reserva altura mínima para manter o painel legível mesmo sem linhas. O painel pode receber foco pelo teclado para rolar conteúdo customizado extenso. Alternar loading não reinicia a rolagem nem altera seleção, expansão ou página. O estado intercepta o ponteiro sobre a tabela, 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 usa role="grid" nas células e navegação por setas. A sequência de Tab percorre os controles interativos em ordem do DOM, incluindo os botões da barra antes dos controles das células. Células sem controles são ignoradas; o foco não fica preso na grade.

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

O padrão APG de grid é uma referência para a navegação por setas; a sequência direta de Tab pelos controles interativos segue a decisão D-033 deste projeto.

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 (role="rowheader" nas células marcadas com row-header). A barra de ações e o rodapé não fazem parte da grade.

As setas movem o foco entre as células. Para tornar cada checkbox e botão diretamente alcançável por Tab, os controles das células participam da sequência global de foco. Escape ou F2 leva do controle à superfície da célula; as setas movem o foco a partir dela.

Sequência de Tab e foco

• Tab percorre os controles habilitados e visíveis do cabeçalho e das linhas na ordem do DOM. Shift+Tab percorre a sequência no sentido inverso. Células sem controles são ignoradas; a barra de ações vem antes da grade e o rodapé permanece depois dela.
• Com controles na grade, as superfícies das células não criam paradas extras de Tab. Sem controles, uma única célula ativa fica disponível como entrada para a navegação por setas.
• Cada controle mantém seu foco visível e seu teclado nativo. Para voltar à navegação entre células, pressione Escape ou F2; a superfície focada não precisa estar na sequência de Tab para receber foco programático.
• 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
Ctrl+Home / Ctrl+End	Move para a primeira célula da grade / última célula da grade.
Home / End	Move para a primeira / última célula da linha atual.
Page Down / Page Up	Move a quantidade de linhas definida por visibleRows, preservando a coluna quando possível e acompanhando a rolagem.
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.

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 das células na ordem do DOM. Depois do último ou antes do primeiro controle da grade, o foco sai para o próximo ou o anterior elemento focalizável da página.
• 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.

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.

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.

Agrupamento de linhas e colunas

Prefira tabelas simples. Quando houver uma hierarquia real nos dados, use várias linhas em br-table-header, com col-span e row-span nas células do cabeçalho. Só os cabeçalhos finais que ocupam uma coluna podem ter ordenação; títulos que agrupam colunas não ordenam os dados.

No corpo, atribua a mesma chave row-group às linhas contíguas de um grupo. Cada chave deve identificar um único bloco contíguo. Use row-span para mesclar células dentro desse bloco e row-header no rótulo compartilhado. Omita nas linhas seguintes as células já ocupadas por uma mescla. As mesclas são limitadas às linhas disponíveis do cabeçalho ou grupo e não atravessam páginas. col-span e row-span aceitam inteiros entre 1 e 1000; valores inválidos usam 1.

• Seleção: cada linha continua selecionável individualmente; o checkbox do cabeçalho seleciona todas as linhas selecionáveis de todos os grupos.
• Ordenação: move grupos completos, comparando o valor da primeira linha de cada grupo na coluna final escolhida. sort-value continua tendo precedência sobre o texto. A ordem interna dos membros é preservada e remover a ordenação restaura a ordem original dos grupos. No modo manual, a aplicação deve manter os grupos completos na resposta.
• Altura da viewport: heightRows define quantos itens lógicos (linhas independentes ou grupos) são reservados no cálculo da altura. Em grupos com várias linhas, a altura inclui todas as linhas físicas do grupo. Sem essa prop, a altura acompanha visibleRows. Ela não altera paginação ou virtualização.
• Paginação: pageSize, totalItems e o contador da paginação contam grupos e linhas independentes. visibleRows continua expressando a capacidade visual em linhas. Na paginação remota, forneça grupos completos e o total em grupos. A grade não inventa contagens ou índices globais de linhas remotas quando conhece apenas o total de grupos.
• Virtualização: a janela cresce até os limites de cada grupo tocado. Um grupo maior que a viewport permanece montado por inteiro; prefira grupos pequenos para manter a economia de DOM.
• Expansão: detalhes de linhas agrupadas aparecem após as linhas de dados do grupo, evitando sobreposição com as células mescladas.
• Teclado e acessibilidade: as setas atravessam células mescladas sem prender o foco; cabeçalhos de linha usam rowheader e as mesclas expõem seus spans e posições lógicas em ARIA. O anúncio final depende do navegador/leitor de tela.

O preset Agrupamento de linhas e colunas apresenta 12 unidades com três servidores cada, dois níveis de cabeçalho, seleção, ordenação, paginação e virtualização. Uma página comporta dez unidades e a viewport mostra três linhas.

Na API programática, TableRowData.rowGroup, TableCellData.rowSpan, TableCellData.colSpan e TableCellData.rowHeader equivalem aos atributos. TableData.headerRows recebe a matriz completa de cabeçalhos e, quando não vazia, tem precedência sobre columns:

await table.setData({
  columns: [],
  headerRows: [
    [
      { content: 'Unidade', rowSpan: 2, sortable: true },
      { content: 'Equipe', colSpan: 2 },
    ],
    [
      { content: 'Nome', sortable: true },
      { content: 'Cargo', sortable: true },
    ],
  ],
  rows: [
    {
      rowGroup: 'brasilia',
      cells: [
        { content: 'Brasília', rowSpan: 2, rowHeader: true },
        { content: 'Ana', sortValue: 'Ana' },
        { content: 'Analista' },
      ],
    },
    { rowGroup: 'brasilia', cells: [{ content: 'Carlos' }, { content: 'Técnico' }] },
  ],
});

Tabelas sem row-group e sem cabeçalho multinível mantêm o contrato anterior.

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 conta linhas independentes ou grupos completos, 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

heightRows

Atributo	height-rows
Descrição	Quantidade de itens lógicos usada somente para calcular a altura da viewport. Cada grupo contíguo conta como um item; a altura inclui todas as linhas físicas que compõem os grupos reservados. Não altera paginação, rolagem ou virtualização. Quando omitida, acompanha visibleRows.
Tipo	number
Valor padrão	---

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 em um painel central com scrim sobre toda a tabela, incluindo barra de ações e paginação. O scrim fica limitado ao componente. 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 itens pertencentes a cada página (linhas independentes ou grupos completos).
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'

sortStrategy

Atributo	sort-strategy
Descrição	Define se a tabela ordena as linhas localmente ou deixa a aplicação aplicar a ordenação solicitada. Em manual, a tabela mantém os indicadores e emite brTableSortChange, mas não reordena as linhas; use setData() para fornecer os resultados customizados ou remotos. Valores não reconhecidos usam a estratégia local.
Tipo	"local" | "manual"
Valor padrão	'local'

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 independentes e grupos 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"	Scrim local e área do painel de carregamento sobre a tabela inteira.
"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 sequência de Tab percorre os controles habilitados e visíveis do cabeçalho e das linhas na ordem do DOM, depois dos botões da barra e antes do rodapé. Células sem controles são ignoradas. Shift+Tab percorre os controles na ordem inversa; o foco sai da tabela nos limites sem ficar preso.

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 cada controle alcançado por Tab e a superfície da célula usada pela navegação com setas. Enter ou F2 na superfície 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 todos os controles da tabela 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

A tabela materializa sua janela de linhas internamente. visibleRows define a capacidade visual e pageSize define a página lógica. Ao usar row-group, a janela inclui grupos completos para preservar as células mescladas. Não aplique uma segunda virtualização sobre os mesmos elementos sem coordenar o modelo de dados; para consultas extensas, combine paginação remota com grupos completos.

heightRows controla somente a altura reservada para a viewport. A contagem considera grupos como um item lógico e inclui todas as linhas físicas dos grupos selecionados. Sem heightRows, a altura acompanha visibleRows; paginação e virtualização permanecem independentes.

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

Gráfico