TanStack Table React Query Pagination: Bewährte Vorgehensweisen

TanStack Table React Query Pagination mit serverseitigen Daten: stabile Query-Keys, klare API-Verträge und eine praktische Checkliste für SaaS-Templates.

Huifer
Huifer
24. Oktober 202610 min read
Auch verfügbar auf:English · 中文

Geschrieben von Huifer

Ich verwende TanStack Table für das View-Modell und TanStack Query für den Lebenszyklus des Server-Status, weil sich Pagination leichter nachvollziehen lässt, wenn diese Verantwortlichkeiten getrennt bleiben. Beim Aufbau einer Tabelle definiere ich zuerst den Request-Vertrag und verbinde anschließend URL-Status, Query-Keys und Tabellenstatus. Für diesen Artikel liegt kein Produktions-Benchmark vor; die Beispiele sind Umsetzungshinweise und keine gemessenen Performance-Aussagen.

Offizielle Referenzen: TanStack · TanStack Table Pagination · TanStack Query · TanStack Router · Cloudflare Workers · web.dev · MDN

Zuletzt aktualisiert: 2026-10-24 · Changelog

TanStack Table React Query Pagination: Bewährte Vorgehensweisen

TanStack Table React Query Pagination funktioniert am besten, wenn die Tabelle den Darstellungsstatus und TanStack Query die Serverantwort verwaltet. Verwenden Sie für die meisten SaaS-Admin-Tabellen serverseitige Pagination, nehmen Sie Seite und Seitengröße in einen stabilen Query-Key auf und geben Sie genügend Metadaten zurück, damit die Tabelle die Anzahl der vorhandenen Seiten kennt. Dieser Leitfaden richtet sich an React-Entwickler, die entscheiden, ob sie Pagination in einer bestehenden Anwendung implementieren oder ein Template auswählen, dessen Datenschicht dies bereits unterstützt. Wenn die umgebende Architektur eine Rolle spielt, können Sie vor einer Entscheidung SaaS-Templates und Boilerplates vergleichen.

Kurzfassung

  • Verwenden Sie clientseitige Pagination nur, wenn der vollständige Datensatz bewusst in den Browser geladen wird.
  • Verwenden Sie serverseitige Pagination, wenn API, Datenbank, Berechtigungen oder Filter bestimmen, welche Zeilen sichtbar sind.
  • Halten Sie pageIndex und pageSize im Query-Key, damit die Navigation den korrekten Request erzeugt.
  • Verwenden Sie placeholderData: keepPreviousData, wenn die vorherige Seite während eines Fetch-Vorgangs sichtbar bleiben soll.
  • Geben Sie rowCount oder pageCount aus der API zurück, statt den Wert in der Komponente zu schätzen.

Eigenständige Antwort: TanStack Table verwaltet Pagination-Status und Zeilen-Rendering, während TanStack Query jede Seite abruft und cached. Das zuverlässige Muster besteht aus einem gemeinsamen Pagination-Status, einem Query-Key, der diesen Status enthält, und einer API-Antwort mit expliziten Metadaten zur Gesamtzahl der Zeilen.

Was TanStack Table React Query Pagination bedeutet

TanStack Table ist headless: Die Bibliothek stellt Tabellenstatus, Zeilenmodelle und Pagination-Verhalten bereit, entscheidet aber nicht, wie Ihre Daten den Browser erreichen. TanStack Query verwaltet asynchrone Serverdaten, Caching, erneute Requests und Ladeübergänge. Der TanStack Table Pagination Guide dokumentiert die Grenze zwischen clientseitiger und manueller serverseitiger Pagination, während der TanStack Query Overview die Server-State-Schicht erklärt.

Clientseitige und serverseitige Pagination

Bei clientseitiger Pagination empfängt der Browser alle Zeilen und schneidet sie lokal in Seiten auf. Bei serverseitiger Pagination wird jeweils eine Seite angefordert. Keine der beiden Varianten ist automatisch schneller; die richtige Wahl hängt von Zuständigkeit, Autorisierung, Filtern und der Frage ab, ob der Browser den vollständigen Datensatz erhalten sollte.

EntscheidungClientseitige PaginationServerseitige Pagination
DatensatzBereits im Browser geladenÜber eine API oder Datenbank abgefragt
FilterLokal angewendetIm Request-Vertrag angewendet
BerechtigungenDaten sind bereits offengelegtVor der Rückgabe der Zeilen durchgesetzt
MetadatenTabelle kann lokale Zeilen zählenAPI gibt rowCount oder pageCount zurück
Geeignet fürKleine, begrenzte DatensätzeSaaS-Datensätze, Audit-Logs, Abrechnungsdaten

Die Kaufentscheidung hinter der Implementierung

Bei der Kaufentscheidung geht es darum, ob ein Starter bereits eine typisierte Grenze für Serverdaten, URL-Status und einen berechtigungsbewussten Listen-Endpunkt besitzt. Ein Template kann Ihre Domain-Abfrage nicht definieren, aber es kann wiederholte Verdrahtungsarbeit rund um Routing, Ladezustände, Authentifizierung und Deployment reduzieren. Prüfen Sie vor der Auswahl dessen Query-Cache, Navigationsverhalten und Pagination-Metadaten.

Die Kategorie TanStack Ship Templates ist die passende Produktfläche, wenn Sie diese Grundlage vergleichen möchten, statt eine Tabellenkomponente in einen ansonsten unabhängigen Stack zu kopieren.

Entwerfen Sie zuerst den Pagination-Vertrag

Ein stabiler Vertrag verhindert die meisten Fehler bei der TanStack Table- und TanStack Query-Pagination. Definieren Sie pageIndex, pageSize, eine Allowlist für sort, serialisierte filters und rowCount, bevor Sie den Hook schreiben. Die Anzahl muss Filter und Autorisierung berücksichtigen.

Der Browser sollte einen kleinen, serialisierbaren Request senden. URLSearchParams stellt ein standardisiertes Kodierungsmodell bereit; siehe die MDN-Referenz zu URLSearchParams. Validieren Sie jeden Wert auf dem Server erneut, weil Client-Validierung keine Autorisierungsgrenze darstellt.

Eine typisierte Antwortstruktur

Diese Antwort ist bewusst einfach gehalten: Die Tabelle benötigt Zeilen und eine Anzahl, während die Query-Schicht einen vorhersehbaren Promise- und Fehlerpfad benötigt.

typescript
// api/orders.ts
export type OrderPage = {
  rows: Order[]
  rowCount: number
}

export type OrderPageRequest = {
  pageIndex: number
  pageSize: number
  status?: "open" | "paid" | "refunded"
}

export async function fetchOrders(
  request: OrderPageRequest,
  signal?: AbortSignal,
): Promise<OrderPage> {
  const params = new URLSearchParams({
    page: String(request.pageIndex + 1),
    pageSize: String(request.pageSize),
  })

  if (request.status) params.set("status", request.status)

  const response = await fetch(`/api/orders?${params}`, { signal })
  if (!response.ok) throw new Error("Unable to load orders")
  return response.json() as Promise<OrderPage>
}

Das + 1 wandelt den nullbasierten Tabellenstatus in eine API mit einsbasierten Seiten um. Testen Sie die erste und die letzte Seite ausdrücklich. Der TanStack Query Query-Key Guide behandelt Request-Variablen als Cache-Identität.

Query-Keys müssen jede Request-Variable enthalten

Wenn sich status ändert, der Query-Key aber nicht, kann die Komponente eine Seite für den falschen Filter anzeigen. Wenn sich pageSize ändert, der Key aber nur pageIndex enthält, können gecachte Daten unter einem inkompatiblen Request wiederverwendet werden. Nehmen Sie jede Variable auf, die die zurückgegebenen Zeilen verändert.

tsx
import {
  keepPreviousData,
  useQuery,
} from "@tanstack/react-query"

const paginationKey = [
  "orders",
  { pageIndex, pageSize, status },
] as const

const ordersQuery = useQuery({
  queryKey: paginationKey,
  queryFn: ({ signal }) =>
    fetchOrders({ pageIndex, pageSize, status }, signal),
  placeholderData: keepPreviousData,
})

keepPreviousData ist eine Entscheidung für den Übergang und kein Mechanismus für Korrektheit. Zeigen Sie an, dass eine neue Seite geladen wird, damit vorherige Zeilen nicht mit den aktuellen Ergebnissen verwechselt werden. Siehe die Dokumentation zu paginierten Queries.

Verbinden Sie TanStack Table mit dem Query-Status

Setzen Sie bei serverseitiger Pagination manualPagination: true, damit die Tabelle die Antwort nicht erneut aufteilt. Übergeben Sie rowCount, damit die Tabelle die Seitenanzahl ableiten kann. Siehe den Abschnitt zur manuellen Pagination.

tsx
import {
  getCoreRowModel,
  useReactTable,
} from "@tanstack/react-table"

const table = useReactTable({
  data: ordersQuery.data?.rows ?? [],
  columns,
  getCoreRowModel: getCoreRowModel(),
  manualPagination: true,
  rowCount: ordersQuery.data?.rowCount ?? 0,
  state: { pagination: { pageIndex, pageSize } },
  onPaginationChange: setPagination,
})

Die wichtige Invariante lautet: Derselbe Status erreicht sowohl queryKey als auch state.pagination. Lesen Sie den TanStack Table Guide zu kontrolliertem Status, wenn ein anderer Besitzer den Tabellenstatus synchronisieren muss.

Setzen Sie die Seite zurück, wenn sich Filter ändern

Ein Filter kann die aktuelle Seite ungültig machen. Wenn Seite 8 auf zwei Seiten einschränkt, erzeugt pageIndex 7 ein leeres Ergebnis. Setzen Sie pageIndex auf 0 zurück, wenn sich ein Filter oder eine Sortierung ändert.

Speichern Sie Pagination und Filter für teilbare Listen in den Search-Parametern des Routers. TanStack Router Search-Parameter stellt das typisierte Routing-Modell bereit; vermeiden Sie getrennte Kopien im URL- und Komponentenstatus.

Behandeln Sie Ladezustände, Fehler und leere Seiten

Pagination kennt mehr Zustände als „Zeilen oder keine Zeilen“. Trennen Sie initiales Laden von einem Hintergrundübergang, deaktivieren Sie doppelte Navigation, bieten Sie eine Retry-Möglichkeit, unterscheiden Sie gefilterte Leere von einer Seite außerhalb des gültigen Bereichs und invalidieren Sie betroffene Queries nach Mutationen.

Der TanStack Query Guide zur Invalidation ist die richtige Stelle, um das Aktualisieren von Listen-Queries nach Schreibvorgängen zu betrachten. Patchen Sie nicht manuell jede Seite, sofern Sie kein klares Konsistenzmodell haben; Invalidation lässt sich oft leichter überprüfen.

Konkrete Implementierungsgrenzen

Problem: Die Tabelle zeigt nach einer Änderung der Seitengröße doppelte Zeilen.

Ursache: Die alte Seite blieb im Query-Key erhalten oder die Tabelle wendete weiterhin ein clientseitiges Zeilenmodell auf serverseitig paginierte Daten an.

Lösung: Nehmen Sie pageSize in den Key auf, setzen Sie manualPagination: true und setzen Sie pageIndex bei einer Größenänderung auf null zurück.

Ergebnis: Die Benutzeroberfläche fordert eine klar definierte Serverseite an und rendert sie. Das ist ein Ergebnis zur Korrektheit und keine gemessene Performance-Aussage.

Problem: Ein Benutzer kann eine nicht autorisierte Seite oder einen nicht autorisierten Filter anfordern.

Ursache: Der Endpunkt vertraut den Feldern aus der Query-Zeichenfolge und prüft Berechtigungen nur in der React-Komponente.

Lösung: Validieren Sie Seitengrenzen, verwenden Sie eine Allowlist für Sortierfelder und wenden Sie den Tenant- oder Benutzerbereich in der Server-Abfrage an. Die Cloudflare Workers-Dokumentation und die Cloudflare D1-Dokumentation sind Ausgangspunkte, wenn dieser Endpunkt am Edge mit einer datenbankgestützten Anfrage läuft.

Ergebnis: Der Browser empfängt nur Zeilen, die durch die serverseitige Richtlinie erlaubt sind. Anwendungsspezifische Autorisierungstests sind weiterhin erforderlich.

Performance- und Accessibility-Prüfungen

Pagination reduziert die pro Request übertragene Datenmenge, macht eine Tabelle aber nicht automatisch barrierefrei oder schnell. Messen Sie das für Benutzer sichtbare Ergebnis mit einem repräsentativen Datensatz und realistischen Netzwerkbedingungen. web.dev Web Vitals behandelt die benutzerorientierten Metriken, die Sie beobachten sollten, während der MDN-HTTP-Überblick das Request- und Antwortverhalten unterhalb Ihres Fetch-Aufrufs erklärt.

Ich prüfe diese Details, bevor ich die Tabelle als bereit betrachte:

  • Seiten-, Gesamtseiten- und Ladezustände werden für assistive Technologien bereitgestellt.
  • Die Steuerelemente für „Zurück“ und „Weiter“ werden an den richtigen Grenzen deaktiviert.
  • Der Tastaturfokus bleibt bei einem Seitenübergang erhalten.
  • Die API begrenzt pageSize, weist ungültige Sortierfelder zurück und gibt eine echte Anzahl zurück.

Wenn Ihre Datenbank Supabase ist, lesen Sie die Supabase-Datenbankdokumentation für die Query- und Autorisierungsschicht. Wenn Sie eine andere Datenbank verwenden, gilt dasselbe Prinzip: Die Pagination-Oberfläche sollte den tatsächlichen Vertrag des Servers abbilden und nicht Annahmen, die in einer Komponente verborgen sind.

Was ich messen würde und was ich nicht behaupten würde

Messen Sie Request-Dauer, Antwortgröße, Fehlerrate und Interaktionszeit in Ihrer eigenen Umgebung. Ich würde ohne kontrollierten Benchmark keine feste prozentuale Verbesserung behaupten; die Ergebnisse variieren je nach Indizes, Serialisierung, Netzwerkentfernung, Cache-Status und Rendering-Kosten.

Testen Sie die erste, mittlere und letzte Seite, leere und nur eingeschränkt berechtigte Ergebnisse, langsame und fehlgeschlagene Antworten, das Verhalten von „Zurück“ und „Weiter“ im Browser sowie eine direkt geöffnete URL mit Pagination-Parametern.

Welches Template passt zu diesem Anwendungsfall?

Wählen Sie ein Template oder einen Starter anhand der umgebenden Fähigkeiten aus und nicht danach, ob ein Tabellenbeispiel enthalten ist. Prüfen Sie die typisierte Grenze der Listen-Query, Authentifizierung und Tenant-Scope, die Invalidation-Konvention, den URL-Status und den Deployment-Pfad.

Wenn Sie Implementierungsgrundlagen vergleichen, verwenden Sie den Entscheidungsleitfaden für SaaS-Boilerplates, um diese Fähigkeiten gemeinsam zu bewerten. Durchsuchen Sie anschließend TanStack Templates und suchen Sie das Template, dessen Routing-, Datenlade- und Deployment-Entscheidungen zu Ihrem Produkt passen. Die Entscheidung besteht darin, welche Grundlage die wenigsten nicht zugeordneten Grenzen rund um Pagination hinterlässt.

Fazit: eine zuverlässige Pagination-Entscheidung

Bei TanStack Table React Query Pagination sollte die Tabelle für Pagination-Status und Rendering verantwortlich sein, TanStack Query für Serverdaten und die API explizite Metadaten zur Zeilenanzahl zurückgeben. Verwenden Sie serverseitige Pagination, wenn Filter, Berechtigungen oder die Datenbankzuständigkeit eine Rolle spielen; verwenden Sie clientseitige Pagination nur, wenn der vollständige Datensatz bewusst lokal gehalten wird.

Nächster Schritt: Vergleichen Sie die SaaS-Boilerplate-Optionen mit den erforderlichen Fähigkeiten Ihrer Listen-Query und durchsuchen Sie anschließend die verfügbaren Templates, bevor Sie die Tabellengrenze implementieren.

FAQ: Sollte TanStack Table clientseitige oder serverseitige Pagination verwenden?

Verwenden Sie clientseitige Pagination, wenn der vollständige Datensatz bereits geladen und sicher für den Browser zugänglich ist. Verwenden Sie serverseitige Pagination, wenn die Zeilen aus einer Datenbank stammen, Filter die Autorisierung beeinflussen oder der Datensatz schrittweise geladen werden soll. Tabellenkonfiguration und API-Vertrag sollten diese Entscheidung ausdrücklich machen, statt beide Modi versehentlich zu vermischen.

FAQ: Wie sollte TanStack Query paginierte Tabellendaten cachen?

Nehmen Sie jede Request-Variable, die die Antwort verändert, in den Query-Key auf: Seitenindex, Seitengröße, Filter, Sortierung, Tenant-Scope und jeden anderen serverseitigen Parameter. Verwenden Sie keepPreviousData, wenn ein stabiler Übergang hilfreich ist, zeigen Sie aber einen Ladeindikator an, damit Benutzer wissen, dass die sichtbaren Zeilen noch den vorherigen Request darstellen können.

FAQ: Benötigt ein SaaS-Template integrierte TanStack Table Pagination?

Nicht unbedingt. Der Wert eines Templates liegt in den Grenzen rund um die Tabelle: typisiertes Laden von Daten, Authentifizierung, URL-Status, Invalidation-Konventionen und Deployment. Eine Komponente kann später ergänzt werden. Prüfen Sie vor dem Kauf die tatsächliche Architektur des Templates und wählen Sie die Option, die Ihr Query- und Berechtigungsmodell unterstützt, ohne wichtige Abläufe zu verbergen.

Weiterführende Lektüre: Tanstack Query V5 Best Practices · Tanstack Query V5 Migration And Best Practices · Tanstack Query V5 Migration And Best Practices 2026

Offenlegung und Einschränkungen

Dieser Artikel ist technische Orientierung und kein Benchmark, kein Sicherheits-Audit und keine Garantie für ein bestimmtes Ergebnis. Aussagen sind nach ihrer Grundlage gekennzeichnet: Umsetzungsbeispiele sind berechnet oder illustrativ, Dokumentationsreferenzen sind aus den verlinkten Quellen gemessen und umgebungsspezifische Ergebnisse sind bis zum Test unbekannt. Ich habe keine materielle Verbindung zu den hier verlinkten externen Dokumentationsprojekten. Wenn Sie einen Fehler finden, verwenden Sie den Changelog oder kontaktieren Sie den Autor über die About-Seite; Korrekturen sollten anhand der relevanten Bibliotheks- und Runtime-Dokumentation vorgenommen werden.