Componentes

Data Table

beta

A camada de ordenação, seleção e paginação sobre a Table. Use quando a lista é grande o bastante para o usuário precisar operar sobre ela.

Ainda não é estável porque Rota não varrida pelo sensor. Ausência de medição não é aprovação. O contrato de maturidade explica o que cada requisito exige.

@voxmente/ui/components/ui/data-table

Orientação

A camada de ordenação, seleção e paginação sobre a Table. Entra quando a lista é grande o bastante para o usuário precisar operar sobre ela.

Quando usar

A lista passa do que cabe numa tela e o usuário precisa navegar por páginas.
Existe ação em lote: selecionar várias linhas e aplicar alguma coisa a todas.
A ordem importa e muda conforme a pergunta que o usuário está fazendo.

Quando não usar

Para uma lista curta e estável. A Table simples entrega o mesmo com menos peso.
Quando a operação real é busca, e não ordenação: talvez o caminho seja filtro e busca, não paginação.
Para dados que não são tabulares só porque a tabela é conveniente.

Playground

	Turma
Marina Alves	7º ano B
Diego Farias	7º ano B

Ordenação da coluna Alunosorted

Estadodemonstração

<DataTableContent>
  <TableHeader>
    <TableRow>
      <DataTableColumnHeader>Aluno</DataTableColumnHeader>
      <DataTableColumnHeader>Turma</DataTableColumnHeader>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
  <TableCell>Marina Alves</TableCell>
  <TableCell>7º ano B</TableCell>
</TableRow>
  </TableBody>
</DataTableContent>

Anatomia

As partes deste componente e como se aninham. A árvore vem das demonstrações desta página, então descreve um exemplo que renderiza.

DataTable
  └─ DataTableToolbar
    └─ DataTableSearch
  └─ DataTableContent
    └─ TableHeader
      └─ TableRow
        └─ DataTableColumnHeader
    └─ TableBody
      └─ TableRow
        └─ TableCell
      └─ TableRow
        └─ TableCell
  └─ DataTablePagination
    └─ DataTableCount

A anatomia de toda tela de lista do Backoffice: toolbar, tabela e paginação. Deliberadamente apresentacional — não embute TanStack Table nem nenhum motor de estado; ordenação, filtro, seleção e paginação entram como props controladas por quem consome.

Sessão	Data	Responsável
Leitura em voz alta	28/08/2026	Prof. Renata Souza
Roda de conversa	26/08/2026	Prof. Iago Prado

2 de 34 sessões

Coluna ordenável

sorted e onSort são controlados por quem consome. Sem onSort, a coluna vira um rótulo estático — nem toda coluna precisa ser ordenável, e o cabeçalho não finge que é. Como onSort é um manipulador de evento, a tabela ordenável precisa viver num componente de cliente.

		Turma
Marina Alves	82%	7º ano B

Carregando

DataTableSkeleton preenche linhas fantasma com a mesma altura das reais, para a tela não pular quando os dados chegam.

Aluno	Turma	Progresso

Vazio

DataTableEmpty ocupa a linha inteira em vez de substituir a tabela inteira — o cabeçalho continua dizendo quais colunas existem.

Aluno	Turma	Progresso
Nenhum aluno encontrado para este filtro.

Célula formatada, ações e paginação

Célula formatada é composição livre: qualquer conteúdo cabe num TableCell, aqui um Badge para status. Ações de linha também não são API do DataTable — é um DropdownMenu comum na última coluna. A paginação em si (botões Anterior/Próxima) é responsabilidade de quem consome: DataTablePagination só organiza o layout do rodapé, não sabe navegar página nenhuma. E o que o pacote não tem: seleção de linha e visibilidade de coluna não existem como prop do DataTable — quem precisar monta com Checkbox e DropdownMenuCheckboxItem por conta própria, e filtro avançado é o mesmo raciocínio da busca, um input controlado fora do componente.

Aluno	Status	Ações
Marina Alves	Em dia
Iago Prado	Pendente

2 de 27 alunos

Acessibilidade

O que o componente já garante, e o que continua sendo responsabilidade da tela.

O estado de ordenação precisa ser anunciado no cabeçalho, não apenas indicado por uma seta.
A caixa de seleção do cabeçalho precisa de nome acessível próprio — “selecionar todas as linhas”.
Mudar de página troca o conteúdo sem recarregar: o usuário de leitor de tela precisa saber que o conteúdo mudou.

Componentes relacionados

Vizinhos que resolvem o problema parecido. Os links são resolvidos contra o registro.

Referência da API

Extraída do TypeScript de @voxmente/ui a cada build. Se divergir do código, o código mudou.

DataTableColumnHeader

Prop	Tipo	Padrão
align	"end" \| "start"	"start"
onSort	(() => void)	—
sorted	false \| "desc" \| "asc"	false

Também aceita as props de React, incluindo className e os atributos de DOM.

DataTableSkeleton

Prop	Tipo	Padrão
columns*	number	—
rows	number	5

DataTable, DataTableContent, DataTableCount, DataTableEmpty, DataTablePagination, DataTableSearch, DataTableToolbar, DataTableToolbarActions, TableBody, TableCell, TableHeader, TableRow não têm props próprias — aceitam apenas as props herdadas, incluindo className e os atributos de DOM.

Pendência editorial: exemplo em contexto de produto. A lacuna aparece aqui em vez de ser preenchida com orientação inventada.

Origem do dado

Orientação, acessibilidade e relacionados: documentação
Anatomia: exemplo desta página
Demonstrações e playground: componente real de @voxmente/ui
Referência da API: TypeScript do pacote
Cor, espaçamento e raio das demonstrações: tokens de theme.css