Tworzenie zaawansowanych tabel w aplikacjach webowych to jedno z tych zadań, które z pozoru wydaje się proste – aż do momentu, gdy użytkownik oczekuje sortowania, filtrowania, paginacji, grupowania, elastycznego stylowania i wydajności przy tysiącach wierszy danych. Wówczas okazuje się, że klasyczne komponenty tabelowe nie nadążają za potrzebami projektowymi i biznesowymi. W tym artykule pokażę Ci, czym jest TanStack Table, jak działa podejście headless, czym różni się od tradycyjnych bibliotek komponentowych oraz jak krok po kroku stworzyć z jej pomocą w pełni funkcjonalną, a jednocześnie dopasowaną do własnych potrzeb tabelę. Niezależnie od tego, czy tworzysz dashboard analityczny, system CMS czy aplikację biznesową – TanStack Table może stać się jednym z Twoich najważniejszych narzędzi.
TanStack Table (wcześniej znana jako React Table) to zaawansowana biblioteka JavaScript służąca do budowania dynamicznych, w pełni konfigurowalnych tabel i siatek danych (data grids). Jej największym wyróżnikiem jest to, że działa w modelu headless UI – co oznacza, że dostarcza wyłącznie logikę, zarządzanie stanem i narzędzia do obsługi interakcji, bez narzucania struktury HTML czy stylów CSS.
Tradycyjne biblioteki komponentowe (np. AG Grid czy Material UI Table) oferują gotowe komponenty z narzuconą strukturą i wyglądem. Działa to dobrze, dopóki nie potrzebujesz pełnej kontroli nad wyglądem lub integracji z własnym systemem designu. TanStack Table idzie w przeciwnym kierunku: pozwala Ci całkowicie decydować o tym, jak Twoja tabela wygląda i jak się zachowuje – jednocześnie biorąc na siebie odpowiedzialność za najtrudniejsze elementy: zarządzanie stanem, przetwarzanie danych, sortowanie, filtrowanie czy paginację.
W praktyce oznacza to, że TanStack Table nie renderuje niczego za Ciebie. Zamiast tego, daje Ci dostęp do gotowej logiki, którą możesz dowolnie osadzić w swoich komponentach. Dzięki temu możesz tworzyć tabele:
Chociaż TanStack Table rozpoczęła życie jako biblioteka stricte dla Reacta, dziś wspiera również inne frameworki frontendowe, takie jak: Vue, Svelte, Solid, Qwik. To czyni ją rozwiązaniem przyszłościowym – niezależnie od tego, jaką technologię wybierzesz w swoim kolejnym projekcie, podejście i API TanStack Table pozostaną znajome.
TanStack Table jest szczególnie przydatna, gdy:
– chcesz mieć pełną kontrolę nad wyglądem tabeli: niezależnie od tego, czy używasz Tailwinda, MUI, Chakra UI, czy własnego systemu stylowania – TanStack Table nie narzuca żadnych ograniczeń. To Ty decydujesz o strukturze HTML i CSS.
– integrujesz się z niestandardowym systemem projektowania (Design System). Masz firmowy design system lub musisz ściśle trzymać się wytycznych klienta? TanStack Table bez problemu się w to wpisze, bo nie wymusza gotowych styli ani komponentów.
-potrzebujesz wydajnej obsługi dużych zbiorów danych – dzięki wsparciu dla wirtualizacji i inteligentnemu zarządzaniu stanem, biblioteka świetnie radzi sobie z tabelami zawierającymi tysiące wierszy – bez spowalniania interfejsu.
-wymagasz elastyczności przy implementacji złożonych funkcji interaktywnych: grupowanie danych, rozwijane wiersze, kolumny typu „drag-and-drop”, własne edytory komórek? Wszystko to możesz zbudować na bazie logiki TanStack Table – bez kompromisów.
TanStack Table to biblioteka, która nie dostarcza gotowych komponentów – ale za to daje Ci wszystkie narzędzia do zbudowania dokładnie takiej tabeli, jakiej potrzebujesz. Poniżej znajdziesz kluczowe funkcjonalności wraz z praktycznymi przykładami ich użycia w React.
Sortowanie to jedna z najczęstszych funkcji w tabeli. W TanStack Table możesz bardzo łatwo włączyć sortowanie kolumn. Przykład:
import {
useReactTable,
getCoreRowModel,
getSortedRowModel,
} from '@tanstack/react-table'
const table = useReactTable({
data,
columns,
state: {
sorting,
},
onSortingChange: setSorting,
getCoreRowModel: getCoreRowModel(),
getSortedRowModel: getSortedRowModel(),
})
Wystarczy kliknąć w nagłówek kolumny, by zmienić kierunek sortowania. Możesz też stworzyć własne ikony sortowania i logikę dla typów danych (np. daty, liczby, tekst).
Możesz dodać zarówno filtrację globalną, jak i filtrowanie poszczególnych kolumn – wszystko z własnym UI. Poniżej pokazujemy przykład z filtrowaniem tekstowym kolumny:
{
accessorKey: 'email',
header: 'Email',
filterFn: 'includesString',
}
Własny komponent pola filtrowania:
<input
value={table.getColumn('email')?.getFilterValue() ?? ''}
onChange={(e) =>
table.getColumn('email')?.setFilterValue(e.target.value)
}
/>
TanStack Table wspiera zarówno lokalne, jak i serwerowe stronicowanie – zależnie od Twojego źródła danych. Przykład (lokalne):
const table = useReactTable({
pageCount: -1, // jeśli serwerowe
manualPagination: true,
onPaginationChange: setPagination,
getPaginationRowModel: getPaginationRowModel(),
})
Strony, licznik, „następna/poprzednia” – możesz zaimplementować dowolny interfejs.
Możesz grupować wiersze według jednej lub wielu kolumn, tworząc zagnieżdżoną strukturę danych. Przykład:
{
accessorKey: 'department',
enableGrouping: true,
}
Efekt: dane są grupowane po department, a każda grupa może być rozwijana/zamykana dynamicznie.
Agregacja to niezwykle przydatna funkcjonalność, szczególnie w kontekście aplikacji analitycznych, finansowych czy raportowych. Pozwala ona na automatyczne podsumowanie wartości w kolumnach – np. obliczenie sumy sprzedaży, średniej oceny, liczby zgłoszeń czy maksymalnej wartości.
TanStack Table pozwala przypisać do kolumny własną funkcję agregującą (np. sum, average, count, max, min albo zupełnie własną funkcję), a także zdefiniować, jak dana kolumna powinna się zachować w wierszu grupy.
Poniżej przedstawiamy przykład z sumowaniem wynagrodzenia według działu:
{
accessorKey: 'salary',
header: 'Salary',
aggregationFn: 'sum', // funkcja agregująca
aggregatedCell: ({ getValue }) => `Suma: $${getValue()}`, // widok w wierszu grupy
}
W połączeniu z funkcją grupowania, TanStack Table automatycznie zsumuje wszystkie wartości salary dla każdego department i wyświetli podsumowanie w grupie. Dlaczego to ważne? Ponieważ ułatwia prezentację danych zbiorczych bez dodatkowej logiki po stronie serwera. Możesz łatwo rozbudować UI tabeli o wiersze podsumowania, zestawienia sekcyjne, czy nawet wielopoziomowe agregaty. Dodatkowo masz pełną kontrolę nad formatem prezentacji danych agregowanych – możesz wyróżniać je graficznie, kolorystycznie, dodać ikonki itp.
To funkcja, która szczególnie dobrze sprawdza się w dashboardach, raportach, arkuszach kalkulacyjnych online czy systemach ERP/CRM.
Jeśli Twoja tabela zawiera tysiące wierszy, możesz użyć @tanstack/react-virtual, by renderować tylko widoczne elementy – znacząco poprawiając wydajność, np.: zamiast renderować 10 000 wierszy, renderowanych jest tylko 30 aktualnie widocznych.
Jedną z największych zalet TanStack Table jest to, że daje Ci pełną swobodę w definiowaniu, modyfikowaniu i zarządzaniu kolumnami – zarówno na etapie konfiguracji tabeli, jak i dynamicznie w czasie działania aplikacji. To niezwykle przydatne w projektach, gdzie interfejs musi się dostosowywać do ról użytkowników, preferencji czy kontekstu biznesowego. Poniżej pokazujemy dynamiczne kolumny na podstawie warunku:
const userColumns = showSalary
? [...baseColumns, salaryColumn]
: baseColumns
W tym przykładzie kolumna „salary” będzie widoczna tylko wtedy, gdy showSalary zwróci true – np. gdy użytkownik ma uprawnienia do widzenia danych płacowych.
Co możesz zrobić dzięki personalizacji kolumn? Np.: na podstawie stanu aplikacji, roli użytkownika lub filtra możesz ukrywać lub pokazać kolumnę. Możesz pozwolić użytkownikom przeciągać kolumny (drag-and-drop), aby zmieniali układ tabeli zgodnie z własnymi preferencjami. Co jeszcze? Możesz zapisywać konfigurację kolumn (np. widoczność, szerokość, kolejność) w localStorage, bazie danych lub profilu użytkownika – i przywracać ją przy każdej sesji. Poniżej przykład: ustawianie własnych nagłówków i szerokości:
{
accessorKey: 'createdAt',
header: () => <span>Data utworzenia</span>,
size: 180,
}
TanStack Table wyróżnia się tym, że nie narzuca Ci żadnego stylowania ani struktury HTML. W przeciwieństwie do gotowych komponentów z bibliotek takich jak Material UI czy Bootstrap, TanStack Table pozwala Ci samodzielnie zdefiniować każdy element tabeli: od <table>, przez <thead> i <tbody>, aż po komórki, przyciski sortowania, stronicowania, a nawet loading spinnery.
To podejście daje Ci pełną swobodę integracji z dowolnym systemem projektowania UI – bez zgrzytów, bez przeróbek, bez walki z override’owaniem stylów.
TailwindCSS świetnie współgra z TanStack Table. Dzięki klasom utility możesz bardzo precyzyjnie stylować każdy element tabeli bez potrzeby tworzenia dodatkowych komponentów. Przykładowo:
<table className="min-w-full divide-y divide-gray-200">
<thead className="bg-gray-50">
<tr>
{table.getHeaderGroups().map(headerGroup =>
headerGroup.headers.map(header => (
<th
className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider"
key={header.id}
>
{header.column.columnDef.header}
</th>
))
)}
</tr>
</thead>
</table>
W powyższym przykładzie nagłówki tabeli są w pełni kontrolowane i wystylizowane z wykorzystaniem Tailwinda – ale równie dobrze możesz użyć własnych klas CSS lub dowolnego innego systemu stylów. iezależnie od tego, jak stylujesz aplikację – TanStack Table to wspiera dowolne własne komponenty z logiką renderowania: TailwindCSS, CSS Modules, Styled Components / Emotion, Vanilla CSS, UI frameworki (MUI, Chakra, Bootstrap).
Aby przekonać się „na własnej skórze” jak niesamowity jest TanStack Table radzimy abyś rozpoczął swój pierwszy projekt, w kilku krokach pokażemy Ci jak stworzyć pierwszą tabelę.
1. Zainstaluj niezbędne pakiety:
npm install @tanstack/react-table
Jeśli planujesz obsłużyć duże zbiory danych i zależy Ci na wydajności, warto również dodać wirtualizację:
npm install @tanstack/react-virtual
2. Tworzenie podstawowej tabeli – załóżmy, że masz dane użytkowników. Zacznijmy od definicji danych i kolumn:
const data = [
{ id: 1, name: 'Anna', email: 'anna@example.com' },
{ id: 2, name: 'Tomasz', email: 'tomasz@example.com' },
]
const columns = [
{
accessorKey: 'name',
header: 'Imię',
},
{
accessorKey: 'email',
header: 'Email',
},
]
Następnie inicjalizujemy tabelę:
import { useReactTable, getCoreRowModel } from '@tanstack/react-table'
const table = useReactTable({
data,
columns,
getCoreRowModel: getCoreRowModel(),
})
Teraz renderujemy tabelę:
<table>
<thead>
{table.getHeaderGroups().map(headerGroup => (
<tr key={headerGroup.id}>
{headerGroup.headers.map(header => (
<th key={header.id}>
{/* 🧠 Użyj flexRender, jeśli chcesz renderować niestandardowe komponenty lub JSX */}
{header.isPlaceholder
? null
: flexRender(
header.column.columnDef.header,
header.getContext()
)}
</th>
))}
</tr>
))}
</thead>
<tbody>
{table.getRowModel().rows.map(row => (
<tr key={row.id}>
{row.getVisibleCells().map(cell => (
<td key={cell.id}>
{/* 🧠 To samo dotyczy komórek danych – flexRender obsłuży komponenty, JSX, tekst, liczby itd. */}
{flexRender(
cell.column.columnDef.cell,
cell.getContext()
)}
</td>
))}
</tr>
))}
</tbody>
</table>
Używaj flexRender zamiast bezpośredniego wywołania .renderCell(). flexRender() to funkcja stworzona przez autorów TanStack Table, która obsługuje zarówno wartości proste (np. string, number), jak i funkcje renderujące JSX. Dzięki niej możesz w kolumnach używać np. () => <span>{value}</span> bez ryzyka, że tabela zwróci [object Object] lub nic.
Każdy header i cell może być funkcją renderującą. W definicji kolumn możesz używać funkcji w header i cell, np.:
{
accessorKey: 'email',
header: () => <span>Email 📧</span>,
cell: ({ getValue }) => (
<a href={`mailto:${getValue()}`} className="text-blue-600 underline">
{getValue()}
</a>
)
}
Następnie przechodzimy do punktu 3. czyli dodajemy rozszerzenia logiki:
import {
getSortedRowModel,
getFilteredRowModel,
getPaginationRowModel,
} from '@tanstack/react-table'
const table = useReactTable({
data,
columns,
state: {
sorting,
pagination,
columnFilters,
},
onSortingChange: setSorting,
onPaginationChange: setPagination,
onColumnFiltersChange: setColumnFilters,
getCoreRowModel: getCoreRowModel(),
getSortedRowModel: getSortedRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getPaginationRowModel: getPaginationRowModel(),
})
Dodajemy UI do sortowania (np. klik w nagłówek):
<th
onClick={header.column.getToggleSortingHandler()}
>
{header.column.columnDef.header}
{header.column.getIsSorted() === 'asc' ? ' 🔼' : ' 🔽'}
</th>
Następnie dodajemy prosty filtr:
<input
value={table.getColumn('name')?.getFilterValue() ?? ''}
onChange={e =>
table.getColumn('name')?.setFilterValue(e.target.value)
}
/>
oraz przyciski paginacji:
<button onClick={() => table.previousPage()} disabled={!table.getCanPreviousPage()}>
Poprzednia
</button>
<button onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>
Następna
</button>
4. Dostosuj wygląd tabeli, tutaj masz dowolność, możesz użyć Tailwinda, Styled Components, MUI lub klasycznego CSS. Niżej jest przedstawiony przykład z Tailwind CSS
<table className="min-w-full table-auto border border-gray-200">
<thead className="bg-gray-100">
<tr>
{table.getHeaderGroups().map(headerGroup => (
headerGroup.headers.map(header => (
<th
key={header.id}
className="px-4 py-2 text-left font-semibold text-sm text-gray-600"
>
{header.column.columnDef.header}
</th>
))
))}
</tr>
</thead>
</table>
Gratulacje! Właśnie stworzyłeś swoją pierwszą, w pełni funkcjonalną tabelę z użyciem TanStack Table – z własnymi danymi, sortowaniem, filtrowaniem i paginacją. Od teraz masz fundament, na którym możesz budować bardziej zaawansowane i dopasowane do Twojego projektu rozwiązania.
TanStack Table to narzędzie, które idealnie trafia w potrzeby nowoczesnych zespołów frontendowych: daje maksymalną elastyczność, pełną kontrolę i ogromną skalowalność – bez narzucania jakichkolwiek ograniczeń stylistycznych czy architektonicznych.
W przeciwieństwie do gotowych bibliotek komponentów, które często oferują dużo, ale w pakiecie z trudnymi do obejścia ograniczeniami, TanStack Table działa w duchu „headless-first”. Oznacza to, że wszystko, co widzisz w interfejsie – styl, markup, interakcje – tworzysz Ty, a biblioteka odpowiada jedynie za to, co naprawdę trudne: logikę, stan, wydajność i przetwarzanie danych.
TanStack Table to biblioteka typu headless UI – nie dostarcza gotowych komponentów ani stylów. Zamiast tego daje pełną logikę zarządzania tabelą (sortowanie, filtrowanie, paginacja, grupowanie itd.), a wygląd i strukturę HTML tworzysz samodzielnie. To idealne rozwiązanie, gdy chcesz mieć pełną kontrolę nad interfejsem użytkownika.
Nie! Mimo że najczęściej używana jest w projektach React, TanStack Table wspiera też inne frameworki frontendowe, takie jak Vue, Svelte, Solid czy Qwik. Każda wersja posiada dedykowane API dopasowane do specyfiki danego frameworka.
Nie – wystarczy @tanstack/react-table, by rozpocząć pracę. Jeśli zależy Ci na wydajności przy dużych zbiorach danych, możesz doinstalować @tanstack/react-virtual, który umożliwia wirtualizację (renderowanie tylko widocznych wierszy).
Tak, i to jest jej największa zaleta. TanStack Table nie narzuca żadnego stylowania, co oznacza, że możesz swobodnie integrować ją z dowolnym systemem CSS: Tailwind, Styled Components, Emotion, Material UI, Bootstrap – a nawet własnym design systemem.
Zdecydowanie tak. Jest to dojrzała, stabilna i bardzo wydajna biblioteka używana w wielu profesjonalnych aplikacjach. Dzięki modularności, lekkości i elastycznemu API świetnie sprawdza się w dużych systemach: od paneli administracyjnych, przez aplikacje analityczne, po zaawansowane narzędzia B2B.
