Table

O <tbody>: as linhas de dado.

Não desenha nada por conta própria. O visual da linha mora no TableRow.

A legenda da tabela, num <caption> de verdade. É o nome que o leitor de tela anuncia antes de entrar nas linhas.

Ela vai dentro do Table, e como primeiro filho:

<Table>
  <TableCaption>Notas emitidas em junho de 2025</TableCaption>
  <TableHeader>…</TableHeader>
  <TableBody>…</TableBody>
  <TableFooter>…</TableFooter>
</Table>

O instinto é escrever esse título numa <p> ou num <h3> logo acima da tabela. Não quebra nada, e custa o nome inteiro: o anúncio vira "tabela, 5 colunas, 12 linhas" e mais nada, porque texto vizinho não nomeia elemento nenhum. Numa tela com duas tabelas (a das notas e a dos pagamentos), quem navega por lista de tabelas ouve as duas com o mesmo nome, que é nome nenhum.

E não há meio-termo: <caption> não tem outro pai legal além de <table>. Solto ao lado do Table, onde o título parece caber melhor, o React derruba a tela:

In HTML, <caption> cannot be a child of <div>. This will cause a hydration error.

Ou é filho da <table>, ou não é legenda.

Quando a tabela já tem um título na página, a legenda continua valendo a pena como nome, só que sem ocupar pixel nenhum:

<TableCaption className="sr-only">Notas emitidas em junho de 2025</TableCaption>

É o que o DataTable faz com o caption dele.

A legenda sai em cima. Para mandá-la para baixo da tabela, caption-bottom na classe. O caption-top da peça sai do caminho sozinho.

Quando não usar

Numa listagem que vem de uma consulta, não monte o <caption> à mão: o DataTable recebe a legenda pela prop caption, e já a escreve dentro da <table> certa (inclusive na variante com altura, onde a tabela é outra).

Para o título visível que encabeça a seção inteira, com ação do lado, é o PageHeader, e não a legenda: TableCaption nomeia a tabela, não a tela.

Uma célula de dado.

Respiro e altura vêm da densidade, então a mesma tabela encolhe junto com o resto em density="compact". Para número, alinhe à direita e use fonte mono pela className.

O rodapé da tabela, num <tfoot> de verdade. É onde mora a linha de totais.

Toda listagem financeira daqui termina em "Total: R$ 248,3K", e até agora essa linha era uma <div> embaixo da tabela. Uma <div> não participa do algoritmo de layout de tabela: ela não conhece a largura de nenhuma coluna, então o total nunca fica debaixo do valor que ele soma. E, numa tabela com moldura própria, ela rola embora junto com o conteúdo.

Dentro da tabela as duas coisas se resolvem sozinhas: a célula divide a largura com a coluna, e o rodapé pode grudar embaixo pelo mesmo mecanismo com que o TableHeader gruda em cima.

<Table>
  <TableHeader>…</TableHeader>
  <TableBody>…</TableBody>
  <TableFooter>
    <TableRow>
      <TableCell colSpan={2}>Total</TableCell>
      <TableCell className="text-right font-mono">{currencyShort(total)}</TableCell>
    </TableRow>
  </TableFooter>
</Table>

O peso é proposital: o rodapé é resumo, e resumo não pode se ler como mais uma linha de dado.

O dinheiro sai abreviado, como no resto da casa: currencyShort, e não o valor por extenso. O currency fica para onde o centavo é o assunto: o valor que a pessoa confirma antes de emitir, e o comprovante depois.

Para grudar o rodapé numa tabela que rola por dentro, o sticky vai na classe, com o degrau de empilhamento da família:

<TableFooter className="sticky bottom-0 z-[var(--rc-z-sticky)] bg-surface">

O fundo não é opcional: sem ele a linha que passa por baixo aparece através do rodapé.

Quando não usar

Numa listagem que vem de uma consulta, não monte o <tfoot> à mão: o DataTable produz a linha sozinho, a partir do total de cada coluna, e ali ele já sabe quais linhas somar, qual coluna esconder no celular e quando grudar.

Uma célula de cabeçalho.

Sai como <th>, em caixa alta e menor, com a altura vinda da densidade. Não quebra linha: cabeçalho quebrado desalinha a coluna toda.

O <thead> da tabela, com a linha que separa do corpo.

Sempre com TableRow e TableHead dentro, cabeçalho montado com <div> some para quem navega a tabela pelo leitor de tela.

Uma linha da tabela.

selected desenha uma barra de acento na lateral, com fundo tênue. A barra é que diz "esta linha", e fundo forte mancha a leitura da linha inteira.

Cor sozinha não é estado, então a primeira célula da linha escolhida abre com um <span> que só o leitor de tela ouve: "Selecionada". É sempre a primeira célula, para quem ouve saber onde o aviso aparece. labels.selected troca o texto quando a tela está em outro idioma.

Não há aria-selected aqui. Ele só é válido dentro de grid ou treegrid, e num <table> simples o navegador descarta o atributo: medido na árvore de acessibilidade, a linha expunha zero propriedades. Adotar role="grid" traria a obrigação de navegar por setas entre as células, que a peça não implementa, e trocaria um defeito por outro maior.