Geschrieben von Huifer
Ich baue TanStack-Table-Admin-Tabellen im Produktivbetrieb, und Filtering ist das Feature, zu dem meine Nutzer als Erstes greifen. Wenn ich globale Suche, Spaltenfilter und clientseitige Sortierung ergänze, entscheide ich zuerst, welche Daten ich bereits im Browser habe und welche ein Server beantworten muss. Diese Grenze explizit zu halten, ist der Unterschied zwischen einem schnell reagierenden Filterfeld und einer Tabelle, die bei jedem Tastenanschlag einen Request sendet.
Offizielle Referenzen: TanStack · TanStack Table Filter-Guide · TanStack Table API-Referenz · TanStack Query · web.dev Performance · Cloudflare Workers · MDN
Zuletzt aktualisiert: 2026-10-31 · Changelog
TanStack Table Filtering: Globale Suche, Spaltenfilter & clientseitige Sortierung
Beim Filtering mit TanStack Table liest die Tabelle Ihr Column-Schema und Ihre Filter-Definitionen ein und berechnet dann, welche Zeilen die Prüfung bestehen. Sie konfigurieren globalen Filter (ein Suchfeld über alle Spalten), Spaltenfilter (Bedingungen pro Spalte) und Sortierung (spaltengetriebene Reihenfolge) über die TableOptions. Dieser Leitfaden richtet sich an React-Entwickler, die entscheiden müssen, ob sie Filtering in eine bestehende App implementieren oder ein SaaS-Template wählen, dessen Datentabelle dieses Verhalten bereits mitbringt. Wenn der umgebende Stack und der Data Layer eine Rolle spielen, können Sie SaaS-Templates und Boilerplates vergleichen, bevor Sie Filter-Code schreiben.
TL;DR
- Spaltenfilter verwenden ein
<input/>(oder Select), das den Filterwert einer Spalte ändert;getFilteredRowModel()wendet das Ergebnis an.- Globales Filtering durchsucht mit einem einzigen Suchtext alle durchsuchten Spalten – via
filterFnsund der SpaltenoptionfilterFn.- Halten Sie Filtering und Sortierung clientseitig, wenn der komplette Datensatz bereits geladen ist; wechseln Sie serverseitig, wenn Zeilen paginiert oder berechtigungsbeschränkt sind.
- Kombinieren Sie bei großen lokalen Datensätzen clientseitiges Filtering mit Sortierung innerhalb einer memoisierten
useMemo-Pipeline.- Vertrauen Sie Fuzzy-Matching und Highlights nicht blind: Prüfen Sie Zeilenzahlen und den Umgang mit Null-Werten, denn TanStack Table behandelt
undefinedundnullunterschiedlich.
Direkte Antwort: TanStack Table liefert Ihnen State, Spaltenoptionen und Row Models für Filtering und Sortierung, holt aber selbst keine Daten. Sie konfigurieren enableColumnFilters, globalFilterFn, die Spaltenoption filterFn und die sorting-Option und liefern dann getFilteredRowModel() und getSortedRowModel(). Liegen die Zeilen hinter einer API, ersetzen Sie die clientseitigen Row Models durch servergetriebene Parameter und lagern das Data Fetching in einen State-Container wie TanStack Query aus.
Warum Filtering und Sortierung die beiden Features sind, die Nutzer zuerst bemerken
Eine datenreiche Oberfläche wird daran gemessen, wie schnell ein Nutzer die Zeile findet, die ihn interessiert. In meinen eigenen Admin-Tabellen haben Suche und Spaltenfilter den Weg zu einem bestimmten Datensatz vom Blättern auf eine getippte Abfrage verkürzt. Der TanStack Table Filter-Guide bringt es auf den Punkt: Filtering ist eine Angelegenheit des Row Models, unabhängig davon, wie die Zeilen in den Browser gelangen. Sortierung gehört in dieselbe Kategorie – sie ordnet bereits verfügbare Zeilen neu. Wenn Sie das verstanden haben, behandeln Sie Suche nicht mehr als „einen Query-Call“, sondern als „Sache des clientseitigen Row Models“.
Was „headless“ für Filtering tatsächlich bedeutet
Headless bedeutet: Die Bibliothek stellt State + Logik bereit, aber keinerlei Markup. Sie rendern das Eingabefeld; Sie entscheiden, wann die Spaltenfilter-UI erscheint. Das ist ein Vorteil: Ein natives <input type="search">, das Sie selbst rendern, ist barrierefrei und bleibt in Ihrem Design-System. TanStack Table führt das Row Model bei jeder filterValue-Änderung erneut aus und stellt instance.filteredRows sowie instance.getRowMeta() für die Zählung bereit, die Sie anzeigen möchten.
Vorher und Nachher in einer echten Tabelle
Vorher: Ich steckte eine Textabfrage in ein <select> und holte bei jeder Änderung die komplette API-Antwort neu – das bedeutete 200–400 ms spürbare Verzögerung und inkonsistente Ergebnisse, wenn die Paginierung zurückgesetzt wurde.
Nachher: Ich ergänzte einen clientseitigen globalFilter mit getFilteredRowModel() über die bereits geladene Seite, sodass Tastenanschläge sofort reagierten, und verlagerte die Sortierung in ein useMemo.
Ergebnis: Das Filterfeld reagiert sofort, und ich sende nur dann einen Server-Request, wenn der Nutzer bewusst die Seite wechselt oder einen Spaltenfilter ändert, der tatsächlich serverseitig lebt. Ich habe diesem Guide kein Benchmark beigefügt; das sind Implementierungserwartungen, keine gemessenen Latenzangaben.
Spaltenfilter und globale Suche einrichten
Spaltenfilter werden pro Tabelle und pro Spalte aktiviert. Sowohl die UI als auch den Wertetyp steuern Sie über ColumnFiltersState. Die globale Suche ist ein einzelner Text, der mit den Spalten verglichen wird, die Sie über die Spaltenoption filterFn einschließen. Beides koexistiert: Die globale Suche ist breit, Spaltenfilter sind eng.
Spaltenfilterung mit einem kontrollierten Eingabefeld aktivieren
import { useReactTable, getCoreRowModel, getFilteredRowModel, ColumnFiltersState } from '@tanstack/react-table'
export function UsersTable({ data }: { data: User[] }) {
const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
const table = useReactTable({
data,
columns,
state: { columnFilters },
onColumnFiltersChange: setColumnFilters,
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
// Spaltenfilter-UI nur dort aktivieren, wo Sie sie zulassen
enableColumnFilters: true,
})
const nameFilter = table.getColumn('name')
return (
<div>
<input
placeholder="Filter by name"
value={(nameFilter?.getFilterValue() as string) ?? ''}
onChange={(e) => nameFilter?.setFilterValue(e.target.value)}
/>
<table>
{table.getHeaderGroups().map((hg) => (
<tr key={hg.id}>
{hg.headers.map((h) => h.isPlaceholder ? null : <th key={h.id}>{h.column.columnDef.header}</th>)}
</tr>
))}
{table.getRowModel().rows.map((row) => (
<tr key={row.id}>{row.getVisibleCells().map((cell) => <td key={cell.id}>{cell.getValue()}</td>)}</tr>
))}
</table>
</div>
)
}
Die drei Bausteine, die das zum Laufen bringen, sind onColumnFiltersChange, getFilteredRowModel() und das Lesen und Schreiben des Filterwerts über column.setFilterValue(). Vergessen Sie getFilteredRowModel(), ändert sich der Spaltenfilter-State zwar, aber die Zeilen werden nie neu bewertet.
Globale Suche über mehrere Spalten
import { useReactTable, getCoreRowModel, getFilteredRowModel, getSortedRowModel } from '@tanstack/react-table'
const columns = [
{ accessorKey: 'name', filterFn: 'includesString' },
{ accessorKey: 'email', filterFn: 'includesString' },
{ accessorKey: 'status', filterFn: 'equalsString' },
]
export function SearchableTable({ data }: { data: User[] }) {
const [globalFilter, setGlobalFilter] = useState('')
const table = useReactTable({
data,
columns,
state: { globalFilter },
onGlobalFilterChange: setGlobalFilter,
globalFilterFn: 'includesString',
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getSortedRowModel: getSortedRowModel(),
})
return (
<input
value={globalFilter}
onChange={(e) => setGlobalFilter(e.target.value)}
placeholder="Search all columns"
/>
)
}
Die filterFn auf Spaltenebene entscheidet, welche Spalten der globale Text durchsucht. 'includesString' matcht case-sensitiv; verwenden Sie 'includesStringSensitive' nur, wenn Groß-/Kleinschreibung eine Rolle spielt. Der Standardwert für globalFilterFn ist auto, das eine typgerechte Funktion wählt – praktisch, aber weniger vorhersagbar, als die Funktion explizit zu deklarieren.
Die Grenze zwischen clientseitigem und serverseitigem Filtering
Das ist die mit Abstand nützlichste Entscheidung bei einer TanStack-Table-Implementierung, und der TanStack Table Filter-Guide macht ausdrücklich deutlich, dass es beide Modi gibt. Clientseitiges Filtering funktioniert, weil getFilteredRowModel() mit Zeilen im Arbeitsspeicher arbeitet. Serverseitiges Filtering bedeutet, dass die Tabelle filtering-Query-Parameter an die API sendet und das Ergebnis rendert – was bedeutet, dass die Row Models für Filtering auf dem Client effektiv No-Ops sind.
Checkliste für die Entscheidung
| Anforderung | Clientseitiges Filtering | Serverseitiges Filtering |
|---|---|---|
| Datensatzgröße | Passt problemlos in den Arbeitsspeicher | Groß, paginiert oder tenant-spezifisch |
| Suchlatenz | Sofort (kein Netzwerk) | Hängt vom API-Roundtrip ab |
| Konsistenz mit der Listenseite | Gut genug | Entspricht den Backend-Regeln aus der Single Source of Truth |
| Berechtigungs-/Tenant-Scoping | Riskant, wenn die Regeln serverseitig liegen | Erforderlich, wenn Zeilen nach Besitz gefiltert werden |
| Sortierung über den vollen Bestand | Sortiert nur geladene Zeilen | Sortiert über den gesamten Backend-Datensatz |
| Typischer Einsatz | Admin-Panel über einer geladenen Seite | Enterprise-Datentabellen, Audit-Logs, Dashboards |
Wenn ich Filtering clientseitig halte, halte ich auch die Sortierung clientseitig, indem ich beide Row Models in einem einzigen useReactTable-Aufruf kombiniere: getFilteredRowModel() vor getSortedRowModel(), damit Filtering und Sortierung dort laufen, wo ihre Metadaten gültig sind. Eine kleine sichtbare Seite zu sortieren ist für einen Bildschirm in Ordnung; das Sortieren eines Exports mit 200.000 Zeilen gehört auf den Server.
Filtering, Sortierung und Paginierung kombinieren
const table = useReactTable({
data,
columns,
state: { columnFilters, sorting },
onColumnFiltersChange: setColumnFilters,
onSortingChange: setSorting,
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getSortedRowModel: getSortedRowModel(),
getPaginationRowModel: getPaginationRowModel(),
initialState: { pagination: { pageSize: 25 } },
})
Die Reihenfolge der Row Models im Options-Objekt ist die Reihenfolge ihrer Verkettung. Halten Sie für den Normalfall genau diese Sequenz ein: erst filtern, dann sortieren, dann paginieren. Verschieben Sie getPaginationRowModel() vor das Filtering, werden die Seiten zuerst in Blöcke geteilt und Ihr Filter sieht nie mehr als eine Seite – ein subtiler Bug, der „fehlende“ Zeilen erzeugt.
Eigene Filterfunktionen und die Null-Value-Falle
TanStack Table bringt eine Reihe eingebauter filterFns mit (includesString, equalsString, inNumberRange, arrIncludes, equals und mehr). Wenn die Standardfunktionen nicht passen, definieren Sie eine eigene Funktion, die für jede Zeile einen Boolean zurückgibt. Die Falle, in die ich am häufigsten tapse, ist der Umgang mit Null-Werten: Die eingebauten Funktionen von TanStack Table behandeln null und undefined unterschiedlich, sodass eine Spalte voller Null-Werte lautlos aus den Suchergebnissen verschwinden kann.
Ein eigener, case-insensitiver Contains-Filter, der null-sicher ist
const customContains: FilterFn<User> = (row, columnId, filterValue) => {
const value: unknown = row.getValue(columnId)
if (filterValue == null || filterValue === '') return true
if (value == null) return false
return String(value)
.toLowerCase()
.includes(String(filterValue).toLowerCase())
}
Hängen Sie ihn in der Spaltendefinition mit filterFn: customContains an oder registrieren Sie ihn global unter filterFns in den Tabellenoptionen. Da filterValue als String aus Ihrem Eingabefeld kommt, wandeln Sie Typen explizit um – ein numerischer Spaltenfilter, der als "42" ankommt, braucht Number(), sonst matcht er nie. Ich halte eigene Funktionen eng gefasst und dokumentiere den akzeptierten Wertetyp, damit die nächste Person, die das Schema liest, nicht überrascht wird.
Performance-Überlegungen und der serverseitige Ausweg
Das Filtern einiger hundert Zeilen ist trivial. Das Filtern von Zehntausenden in einem einzigen Render ist der Punkt, an dem Sie ehrlich zu den Kosten pro Tastenanschlag stehen müssen. getFilteredRowModel() wird bei jeder Filteränderung neu ausgeführt; für kleine Listen ist das in Ordnung, aber bei großen lokalen Datensätzen verpacke ich Daten- und Filter-States in ein einziges useMemo und halte die eigentliche Tabelle unterhalb des Hot Loops. Der web.dev Performance-Guide ist eine gute Referenz für die Rendering- und Memoisierung-Überlegungen hinter diesem Muster.
Wann Sie das Filtering auf den Server auslagern
Verlagern Sie das Filtering auf den Server, wenn einer dieser Punkte zutrifft: Der Datensatz ist paginiert, der Zeilenzugriff ist tenant-spezifisch berechtigungsbeschränkt, der Filter beinhaltet einen Join, den der Client schlicht nicht hat, oder Sie brauchen eine stabile Gesamtzahl. Im Server-Modell wird columnFilters zu Query-Parametern (?name__contains=...), und onColumnFiltersChange von TanStack Table ist die Brücke, die die UI stateful hält, während eine Route oder ein Query Key die Anfrage zur API trägt. Ich kombiniere das mit TanStack Query, sodass der Query Key die Filterwerte enthält und die Navigation sie wiederherstellt.
Welches Template passt zu diesem Use Case?
Filtering, Sortierung und Paginierung gratis zu bekommen ist einer der Gründe, warum ein Entwickler ein Boilerplate wählt, statt eine Tabelle von Hand zu verdrahten. Statt jeden Leser auf dieselbe Seite zu schicken, passen Sie die Entscheidung an den umgebenden Stack an: Wenn Sie Full-Stack-Startpunkte bewerten, zeigt der SaaS-Boilerplate-Vergleich, welches Data-Layer-Verhalten out of the box mitkommt; wenn Sie gezielt eine vorkonfigurierte TanStack-Datentabelle in einem Starter wollen, ist der TanStack-Templates-Katalog die bessere Anlaufstelle. Für Pricing- und Lizenz-Trade-offs beschreibt die Seite Template-Pricing und Lizenzbedingungen, was Sie zahlen und wozu Sie das Template nutzen dürfen.
Bevor Sie wählen: Prüfen Sie, ob die Tabelle des Templates clientseitig auf einer geladenen Seite filtert (typisch für Admin-Dashboards) oder serverseitig über einen Data Layer, und ob das erwartete Volumen zu diesem Modell passt. Ich würde nicht nur deshalb auf serverseitiges Filtering wechseln, um ein Feature-Flag zu kopieren; treffen Sie die Entscheidung anhand Ihres Datensatzes und Ihrer Berechtigungsanforderungen pro Zeile.
Weiterführende Artikel: Tanstack Db 1 0 Rc1 Whats New And Upgrade Guide · Tanstack Table Audit Log D1 Cursors · Tanstack Start Guide 20260711 Comprehensive
FAQ
Filtert TanStack Table eine Server-Antwort automatisch?
Nein. Filtering arbeitet auf den Zeilen, die Sie dem Row Model geben. Kommen Ihre Daten aus einer API, müssen Sie sie entweder vollständig holen und clientseitig filtern oder den Filter-State an den Server senden und getFilteredRowModel() nur über die zurückgegebene Seite anwenden.
Was ist der Unterschied zwischen globalem Filter und Spaltenfiltern?
Der globale Filter ist ein einzelner Textwert, der über die Spalten verglichen wird, die Sie mit filterFn und dem gemeinsamen globalFilterFn eingeschlossen haben. Spaltenfilter sind filterValues pro Spalte, jeweils mit eigener Funktion, meist angetrieben von einem eigenen Eingabefeld unter jedem Header.
Warum zeigt mein Filter keine Ergebnisse?
Die häufigsten Ursachen sind ein fehlendes getFilteredRowModel(), ein Spaltenfilter, der vor getPaginationRowModel() angewendet wird, sodass nur eine Seite durchsucht wird, oder ein Typenkonflikt, bei dem der Filter als String ankommt, der Accessor aber eine Zahl oder null zurückgibt.
Sollte ich die globale Suche debouncen? Nur wenn jeder Tastenanschlag einen Server-Request auslöst. Für reines clientseitiges Filtering über geladene Daten bringt Debouncing Verzögerung ohne Nutzen. Wenn der Wert in einen Query Key fließt, staffeln Sie das Debouncing so, dass URL und Fetch synchron bleiben.
Ist clientseitiges Sortieren über alle Zeilen hinweg korrekt?
Nur innerhalb der in die Tabelle geladenen Zeilen. getSortedRowModel() ordnet den aktuellen Datensatz; eine Datenseite sortiert diese Seite, nicht das gesamte Backend. Für vollständige Korrektheit sortieren Sie serverseitig und steuern sorting über einen Query-Parameter.
Offenlegung und Grenzen: Ich betreibe TanStack Table im Produktivbetrieb, habe diesem Guide aber kein gemessenes Benchmark beigefügt. Die obigen Erwartungen zu Filtering, Sortierung und Performance sind Implementierungsleitlinien aus der offiziellen TanStack-Dokumentation und meiner eigenen Nutzung; behandeln Sie Angaben zu Zeilenzahlen, Latenz und Null-Verhalten als berechnet oder geschätzt, bis Sie sie in Ihrer Umgebung verifiziert haben. Zeilenzahlen können je nach Datensatzgröße, Browser und Netzwerk variieren. Details wie die Verfügbarkeit einzelner Features in einem bestimmten Template sind nutzergeliefert oder [needs source] und sollten anhand der neuesten Release Notes bestätigt werden. Alle Dateipfade und filterFn-Namen spiegeln die TanStack-Table-API zum Zeitpunkt des Schreibens wider; prüfen Sie gegen die neueste Doku, falls sich etwas geändert hat. In diesem Artikel besteht keine materielle Verbindung.
Fazit: Filtern Sie clientseitig, was Sie bereits besitzen – mit getFilteredRowModel() und getSortedRowModel() – und verlagern Sie auf den Server, sobald Zeilen paginiert, berechtigungsbeschränkt oder aus einem Join stammen. Vergleichen Sie, wie Templates diese Grenze handhaben, bevor Sie sie selbst bauen.