DataGrid

Tabela de dados com colunas definidas, ordenação, seleção e vazio.

O DataGrid (do HeroUI Pro) mostra dados em colunas fixas: a lista de Pedidos, o extrato de Créditos, as Fontes. No Admin ele vive dentro de um Widget, sem <table> à mão. Para cartões de métricas use Widget; para listas ricas de uma coluna, ListView.

import { DataGrid, type DataGridColumn } from "@rastreio-x/ui";

Padrão

Informe data, columns, getRowId e um aria-label. A coluna com isRowHeader nomeia a linha para o leitor de tela.

Pedido	Cliente	Estado	Total
ped-8	Marina Souza	Em trânsito	R$ 189,90
ped-7	Rafael Lima	Entregue	R$ 94,50
ped-6	Beatriz Alves	Atrasado	R$ 312,00
ped-5	Caio Martins	Em trânsito	R$ 58,90

Ordenação

allowsSorting na coluna e defaultSortDescriptor (ou sortDescriptor e onSortChange) ligam a ordenação. Use sortFn para ordenar números e datas.

Fonte	Tentativas	Última
Checkout Yampi	128	hoje, 14:20
Webhook Genérico	42	ontem, 18:02
Importação CSV	9	08/10, 10:15

Seleção

selectionMode e showSelectionCheckboxes ligam as caixas por linha. onSelectionChange recebe as chaves selecionadas.

	Cliente	UF
	Marina Souza	SP
	Rafael Lima	RJ
	Beatriz Alves	MG

Nenhum Cliente selecionado

Células próprias

cell desenha a célula. Estado vai em ícone mais texto (Chip), nunca só cor.

Pedido	Cliente	Estado
ped-8	Marina Souza	Em trânsito
ped-7	Rafael Lima	Entregue
ped-6	Beatriz Alves	Atrasado

Sem dados

renderEmptyState mostra o que fazer quando não há linhas.

Pedido	Cliente
Nenhum Pedido ainda Conecte uma Fonte para receber o primeiro.

No Admin

O padrão é DataGrid dentro de Widget, com o rodapé do painel para a nota de fuso e o "Carregar Mais".

Pedido	Cliente	Recebido
ped-8	Marina Souza	hoje, 14:20
ped-7	Rafael Lima	hoje, 11:02
ped-6	Beatriz Alves	ontem, 17:45

Anatomia

DataGrid

O DataGrid é uma peça só, configurada por props. Cada coluna é um objeto DataGridColumn (id, header, accessorKey ou cell, align, allowsSorting, width, pinned).

Propriedades

DataGrid
Prop	Tipo	Padrão	Descrição
`aria-label`*	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`columns`*	`DataGridColumn<T>[]`	-	Definição das colunas.
`data`*	`T[]`	-	Linhas, como array de dados.
`getRowId`*	`(item: T) => string \| number`	-	Devolve o id único de cada linha.
`allowsColumnResize`	`boolean`	`false`	Permite redimensionar as colunas que habilitam isso.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`contentClassName`	`string`	-	Classes da `<table>` interna.
`defaultExpandedKeys`	`Iterable<Key>`	-	Chaves das linhas expandidas inicialmente (não controlado).
`defaultSelectedKeys`	`Selection`	-	Chaves selecionadas inicialmente (não controlado).
`defaultSortDescriptor`	`SortDescriptor`	-	Ordenação inicial (não controlada).
`disabledKeys`	`Iterable<string \| number>`	-	Chaves dos itens desabilitados: não podem ser focados nem selecionados.
`dragAndDropHooks`	`DragAndDropHooks`	-	Hooks de `useDragAndDrop` para arrastar e reordenar itens.
`expandedKeys`	`Iterable<Key>`	-	Chaves das linhas expandidas (controlado).
`footer`	`React.ReactNode`	-	Conteúdo do rodapé da tabela.
`footerClassName`	`string`	-	Classes do rodapé.
`getChildren`	`((item: T) => T[] \| undefined)`	-	Devolve as linhas filhas de um item; habilita linhas em árvore.
`headingHeight`	`number`	`36`	Altura do cabeçalho em pixels. Obrigatória com `virtualized`.
`isLoadingMore`	`boolean`	-	Indica que mais linhas estão sendo carregadas.
`loadMoreContent`	`React.ReactNode`	-	Conteúdo da linha sentinela de carregar mais (por exemplo, um spinner).
`onColumnResize`	`((widths: Map<string \| number, ColumnSize>) => void)`	-	Chamada durante o redimensionamento de uma coluna.
`onColumnResizeEnd`	`((widths: Map<string \| number, ColumnSize>) => void)`	-	Chamada ao terminar o redimensionamento de uma coluna.
`onExpandedChange`	`((keys: Set<Key>) => void)`	-	Chamada quando as linhas expandidas mudam.
`onLoadMore`	`(() => void)`	-	Chamada ao chegar ao fim da lista, para carregar mais itens.
`onReorder`	`((event: DataGridReorderEvent<T>) => void)`	-	Chamada quando os itens são reordenados.
`onRowAction`	`((key: string \| number) => void)`	-	Chamada quando uma linha é acionada.
`onSelectionChange`	`((keys: Selection) => void)`	-	Chamada quando a seleção muda.
`onSortChange`	`((descriptor: SortDescriptor) => void)`	-	Chamada quando a ordenação muda.
`renderEmptyState`	`(() => React.ReactNode)`	-	Conteúdo exibido quando não há itens.
`rowHeight`	`number`	`42`	Altura fixa das linhas em pixels. Obrigatória com `virtualized`.
`scrollContainerClassName`	`string`	-	Classes do contêiner de rolagem.
`selectedKeys`	`Selection`	-	Chaves selecionadas (controlado).
`selectionBehavior`	`'toggle' \| 'replace'`	`"toggle"`	Modelo de interação da seleção: `toggle` marca cada item; `replace` troca a seleção.
`selectionMode`	`'multiple' \| 'none' \| 'single'`	`"none"`	Tipo de seleção permitida: nenhuma, única ou múltipla.
`showSelectionCheckboxes`	`boolean`	`false`	Adiciona uma coluna de caixas de seleção.
`sortDescriptor`	`SortDescriptor`	-	Coluna e direção da ordenação atual (controlada).
`treeColumn`	`string`	-	Id da coluna que mostra a seta da hierarquia.
`treeIndent`	`number`	`20`	Recuo, em pixels, por nível aninhado.
`variant`	`'primary' \| 'secondary'`	`"primary"`	Estilo: `primary` (com sombra suave) ou `secondary` (sem sombra, para uso dentro de cartões).
`verticalAlign`	`'top' \| 'bottom' \| 'middle'`	`"middle"`	Alinhamento vertical do conteúdo das células: `top`, `middle` ou `bottom`.
`virtualized`	`boolean`	`false`	Virtualiza as linhas: só as visíveis são renderizadas (conjuntos grandes).

Animações

CSS
indicativo

A grade não anima o conteúdo; linhas mudam de fundo no hover, no foco e na seleção. O cabeçalho ordenável troca a seta de direção. Com prefers-reduced-motion, a folha global da fachada reduz as transições a 0,01 ms.

Acessibilidade

Tabela do React Aria com papéis grid, row e gridcell; aria-sort marca a coluna ordenada.
Teclado: as setas navegam entre células, Home e End vão às pontas da linha, Enter aciona a linha (onRowAction) e Espaço seleciona.
Dê sempre aria-label e marque a coluna de identidade com isRowHeader.
Evite href por linha: no Admin o link do Pedido fica na primeira célula e a linha abre por onRowAction.
Não use onLoadMore automático: rolagem infinita piora o teclado; use o botão "Carregar Mais".

Boas práticas

Faça

DataGrid dentro de Widget, com a coluna de identidade como link e estado em ícone mais texto.

Evite

Tabela HTML artesanal, ordenação ou filtros fora do que a tela precisa, ou rolagem infinita.

Colunas fixas e poucas; alinhe números à direita com tabular-nums.
No celular, a lista vira cartões (ItemCard); não force a tabela estreita.
Mostre o vazio com renderEmptyState, não uma tabela só com cabeçalho.
Rolagem horizontal fica dentro do grid (contentClassName="min-w-[36rem]").

Relacionados

Widget como contêiner da tabela.
EmptyState para o vazio da tabela.
Chip para o estado em célula.

Nenhum Pedido ainda

Nenhum Pedido ainda