Exemplos de tabela de dados React com TanStack Table
Exemplos de tabela de dados React: TanStack Table v9 com Tailwind | We.Inc
Exemplos tipados de TanStack Table v9 para React: ordenação, busca global, paginação, seleção de linhas, visibilidade de colunas, cabeçalho fixo e dados do lado do servidor, estilizados com Tailwind.
Exemplos de tabela de dados React com TanStack Table
O TanStack Table é uma biblioteca headless de tabelas para React: cuida de ordenação, filtros, paginação e seleção enquanto você escreve o markup. Na versão 9 você registra cada recurso com tableFeatures, adiciona um row model para cada etapa feita no cliente, chama useTable e renderiza cabeçalhos e células com FlexRender. Os exemplos abaixo passaram na checagem de tipos com a 9.3.
Escolha uma abordagem
Linhas
Abordagem
Menos de umas 50, sem interação
Uma tabela HTML simples
De centenas a alguns milhares
TanStack Table, no cliente
Dezenas de milhares ou mais
TanStack Table com ordenação e paginação manuais (no servidor)
Páginas únicas muito longas
Adicione virtualização de linhas
Teste a tabela pronta e depois copie o código que a constrói. A prévia ao vivo nesta página é desenhada com estado simples do React para manter a página leve; o código ao lado é a versão TanStack v9 que faz a mesma coisa no seu app.
Instale @tanstack/react-table.
Liste os recursos de que precisa em tableFeatures, com um slot de row model para cada etapa feita no navegador.
Defina as colunas com createColumnHelper, fora do componente.
Chame useTable com features, columns e data.
Renderize os grupos de cabeçalho e as linhas com o seu próprio markup e FlexRender.
Dê às linhas um id estável com getRowId para que a seleção sobreviva à ordenação e a novas buscas.
Renderize row.getVisibleCells(), não getAllCells(), quando a ocultação de colunas estiver ativa.
Defina o fallback de dados vazios uma vez fora do componente; um novo [] a cada renderização invalida os row models.
Coloque um botão de ordenação dentro de cada th ordenável para que ele seja acessível pelo teclado.
Formate números e datas na função da célula para que a ordenação continue usando o valor bruto.
Perguntas frequentes
React Table é a mesma coisa que TanStack Table?
Sim. O react-table v7 foi renomeado para TanStack Table a partir da v8 e publicado como @tanstack/react-table. A versão 9 mantém a ideia headless, mas pede que você registre os recursos explicitamente, o que deixa os bundles menores.
O TanStack Table inclui estilos?
Não. Ele fornece só o estado e os row models. Você escreve os elementos table, th e td e os estiliza com Tailwind, CSS ou uma biblioteca de componentes como shadcn/ui.
A ordenação e a paginação devem acontecer no servidor?
Quando o conjunto de dados completo é grande demais para enviar ao navegador, sim. Ative as opções manuais, envie o estado de ordenação e de página para a sua API e passe o total de linhas para que os controles de página funcionem.
Como manter o cabeçalho visível durante a rolagem?
Dê ao wrapper uma altura máxima e overflow auto, e deixe o thead sticky com top 0 e uma cor de fundo para que as linhas não apareçam por trás.
Estilo pronto
Se preferir partir de um design pronto, nossa galeria de componentes tem uma tabela de dados em Tailwind com ordenação, busca, seleção de linhas e paginação que você pode copiar em React ou HTML. Para projetos com shadcn/ui, veja nosso guia de formulários e tabelas com shadcn.
Erros comuns
Declarar as colunas dentro do componente sem memoizá-las, o que reconstrói a tabela a cada renderização.
Ativar manualPagination mas continuar passando todas as linhas, de modo que a primeira página mostra tudo.
Inverter a ordem dentro de uma função de ordenação personalizada. Retorne uma comparação crescente; a biblioteca inverte para a ordem decrescente.
Configure o TanStack Table
Instalação
Um único pacote. Ele não tem estilos e não renderiza nada sozinho: você escreve o markup da tabela, e é por isso que combina tão bem com Tailwind.
A menor tabela que funciona
Os recursos são listados no início e passados uma única vez. Mantenha features, columns e o array de dados estáveis (fora do componente ou no estado), senão a tabela reconstrói as linhas a cada renderização.
Recursos e row models
O que registrar para cada comportamento (v9)
Você quer
Recurso
Slot de row model (no cliente)
Clicar em um cabeçalho para ordenar
rowSortingFeature
sortedRowModel: createSortedRowModel()
Uma caixa de busca em todas as colunas
columnFilteringFeature + globalFilteringFeature
filteredRowModel: createFilteredRowModel()
Filtros por coluna
columnFilteringFeature
filteredRowModel: createFilteredRowModel()
Páginas de linhas
rowPaginationFeature
paginatedRowModel: createPaginatedRowModel()
Seleção por checkbox
rowSelectionFeature
Nenhum
Mostrar e ocultar colunas
columnVisibilityFeature
Nenhum
O servidor faz o trabalho
Os mesmos recursos
Sem slots; defina manualSorting, manualFiltering, manualPagination
Uma tabela de dados completa
Ordenar, buscar, paginar, selecionar, ocultar colunas, cabeçalho fixo
Tudo em um só componente, estilizado com classes do Tailwind. A linha de cabeçalho fica no lugar porque o wrapper rola e o thead é sticky. aria-sort informa aos leitores de tela em que direção uma coluna está ordenada.
Dados do lado do servidor
Ordenação e paginação no servidor
Em conjuntos de dados grandes, o servidor ordena e retorna uma página. Deixe de fora os slots de row model, ative as flags manuais e passe rowCount para que a tabela saiba quantas páginas existem. O estado de ordenação e de página comanda a requisição.