Server-Side Table

Server-side pagination, sorting, and filtering with TanStack Query for efficient data fetching and caching.

Loading products from server...

Product Name	Category	Brand	Price	Stock	Rating	In Stock	Release Date

Server-Side Table State

All state is managed with React useState. Data is fetched from a mocked API with delays using TanStack Query. State does NOT persist across page refreshes.

Loading State:Initial Loading...

Total Items (Server):0

Current Page Items:0

Search Query:None

Filter Mode:standard

Active Filters:0

Standard Filters:0

Inline Filters:0

Enhanced Filters:0

Active Enhanced:0

Join Logic:and

Sorting:None

Page:1 of 0 (Size: 10)

Hidden Columns:0

View Full State Object

Server Response:

{
  "totalCount": 0,
  "currentPageItems": 0,
  "page": 1,
  "pageSize": 10
}

Enhanced Filters:

No enhanced filters

Filter Stats:

{
  "totalFilters": 0,
  "hasAndFilters": false,
  "hasOrFilters": false,
  "effectiveJoinOperator": "and",
  "activeFilters": 0,
  "currentMode": "standard"
}

Filter Mode: AND

All conditions must match (stored in columnFilters)

Sorting:

[]

Column Filters State (AND logic):

[]

Global Filter State (OR logic):

""

Pagination:

{
  "pageIndex": 0,
  "pageSize": 10
}

Column Visibility:

{}

💡 Tip: This example uses TanStack Query for server-side data fetching with automatic caching. State is managed with React useState and does NOT persist across page refreshes. For URL state persistence, see the Server-Side Nuqs Table example.

Introduction

The Server-Side Table demonstrates server-side pagination, sorting, and filtering using TanStack Query for efficient data fetching, caching, and state management. This example shows how to handle large datasets by fetching data from a server with automatic caching, background updates, and request deduplication. State is managed with React useState and does NOT persist across page refreshes.

Installation

Add the required components:

npx shadcn@latest add table input button dropdown-menu popover command checkbox select scroll-area separator skeleton tooltip

Add dependencies:

npm install @tanstack/react-table @tanstack/react-query

Note: TanStack Query provides powerful asynchronous state management, server-state utilities, and data fetching capabilities. It handles caching, background updates, and stale data out of the box with zero-configuration.

Required: Sortable Component

This example uses DataTableSortMenu and DataTableFilterMenu which require the Sortable component for drag-and-drop reordering. Follow the DiceUI Sortable installation guide.

Copy the DataTable components into your project. See the Installation Guide for detailed instructions.

Setup

Before using the Server-Side Table, you need to wrap your app with QueryClientProvider. Follow the setup instructions based on your framework:

Next.js App Router

Wrap {children} in app/layout.tsx:

1
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
2

3
const queryClient = new QueryClient({
4
  defaultOptions: {
5
    queries: {
6
      staleTime: 60 * 1000, // 1 minute
7
      refetchOnWindowFocus: false,
8
    },
9
  },
10
})
11

12
export default function RootLayout({ children }) {
13
  return (
14
    <html>
15
      <body>
16
        <QueryClientProvider client={queryClient}>
17
          {children}
18
        </QueryClientProvider>
19
      </body>
20
    </html>
21
  )
22
}

Next.js Pages Router

Wrap <Component> in pages/_app.tsx:

1
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
2

3
const queryClient = new QueryClient({
4
  defaultOptions: {
5
    queries: {
6
      staleTime: 60 * 1000,
7
      refetchOnWindowFocus: false,
8
    },
9
  },
10
})
11

12
export default function App({ Component, pageProps }) {
13
  return (
14
    <QueryClientProvider client={queryClient}>
15
      <Component {...pageProps} />
16
    </QueryClientProvider>
17
  )
18
}

React SPA (Vite, CRA, etc.)

Wrap <App /> in src/main.tsx:

1
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
2

3
const queryClient = new QueryClient({
4
  defaultOptions: {
5
    queries: {
6
      staleTime: 60 * 1000,
7
      refetchOnWindowFocus: false,
8
    },
9
  },
10
})
11

12
createRoot(document.getElementById("root")!).render(
13
  <QueryClientProvider client={queryClient}>
14
    <App />
15
  </QueryClientProvider>,
16
)

Prerequisites

We are going to build a table with server-side data fetching. Here’s what our data structure looks like:

1
type Product = {
2
  id: string
3
  name: string
4
  category: string
5
  brand: string
6
  price: number
7
  stock: number
8
  rating: number
9
  inStock: boolean
10
  releaseDate: Date
11
}

Server-Side Data Fetching

The example uses TanStack Query’s useQuery hook to fetch data from a server. The query automatically refetches when pagination, sorting, or filters change.

API Function

First, create a function that fetches data from your server:

1
type ServerResponse<T> = {
2
  data: T[]
3
  total: number
4
  page: number
5
  pageSize: number
6
}
7

8
type FetchParams = {
9
  page: number
10
  pageSize: number
11
  sorting: SortingState
12
  globalFilter: string | object
13
  columnFilters: ColumnFiltersState
14
}
15

16
async function fetchProducts(
17
  params: FetchParams,
18
): Promise<ServerResponse<Product>> {
19
  // Build query string from params
20
  const queryParams = new URLSearchParams({
21
    page: params.page.toString(),
22
    pageSize: params.pageSize.toString(),
23
    sort: JSON.stringify(params.sorting),
24
    filters: JSON.stringify(params.columnFilters),
25
    search: typeof params.globalFilter === "string" ? params.globalFilter : "",
26
  })
27

28
  const response = await fetch(`/api/products?${queryParams}`)
29
  if (!response.ok) {
30
    throw new Error("Failed to fetch products")
31
  }
32

33
  return response.json()
34
}

Using TanStack Query

Use useQuery to fetch data with automatic caching and refetching:

1
import { useState } from "react"
2
import { useQuery, keepPreviousData } from "@tanstack/react-query"
3
import type { SortingState, ColumnFiltersState } from "@tanstack/react-table"
4

5
function ServerSideTable() {
6
  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 })
7
  const [sorting, setSorting] = useState<SortingState>([])
8
  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
9
  const [globalFilter, setGlobalFilter] = useState<string | object>("")
10

11
  const { data, isLoading, error } = useQuery({
12
    queryKey: [
13
      "products",
14
      pagination.pageIndex,
15
      pagination.pageSize,
16
      sorting,
17
      globalFilter,
18
      columnFilters,
19
    ],
20
    queryFn: () =>
21
      fetchProducts({
22
        page: pagination.pageIndex,
23
        pageSize: pagination.pageSize,
24
        sorting,
25
        globalFilter,
26
        columnFilters,
27
      }),
28
    staleTime: 30000, // Consider data fresh for 30 seconds
29
    gcTime: 5 * 60 * 1000, // Keep in cache for 5 minutes
30
    placeholderData: keepPreviousData, // Keep previous data visible during pagination
31
  })
32

33
  const products = data?.data ?? []
34
  const totalCount = data?.total ?? 0
35

36
  return (
37
    <DataTableRoot
38
      data={products}
39
      columns={columns}
40
      isLoading={isLoading}
41
      config={{
42
        manualPagination: true,
43
        manualFiltering: true,
44
        manualSorting: true,
45
        pageCount: Math.ceil(totalCount / pagination.pageSize),
46
      }}
47
      state={{
48
        pagination,
49
        sorting,
50
        columnFilters,
51
        globalFilter,
52
      }}
53
      onPaginationChange={setPagination}
54
      onSortingChange={setSorting}
55
      onColumnFiltersChange={setColumnFilters}
56
      onGlobalFilterChange={setGlobalFilter}
57
    >
58
      {/* Table components */}
59
    </DataTableRoot>
60
  )
61
}

Key Features

Automatic Caching

TanStack Query automatically caches query results. When you navigate between pages and come back, the data is served from cache instantly.

Background Refetching

Data is automatically refetched in the background when it becomes stale, keeping your UI up-to-date without user intervention.

Request Deduplication

Multiple components requesting the same data will share a single request, reducing server load.

Loading States

TanStack Query provides isLoading and isFetching states:

isLoading: True on initial load (no cached data)
isFetching: True whenever a request is in progress (including background refetches)

1
const { data, isLoading, isFetching } = useQuery({ ... })
2

3
// Show skeleton on initial load
4
{isLoading && <DataTableSkeleton rows={10} />}
5

6
// Show subtle indicator during background refetch
7
{isFetching && !isLoading && <LoadingIndicator />}

Prefetching Next/Previous Pages

To improve navigation performance, you can prefetch adjacent pages in the background. This makes page transitions feel instant when users navigate. You can also track prefetching state to show visual feedback to users:

1
import { useQueryClient } from "@tanstack/react-query"
2
import { useEffect, useState, useRef } from "react"
3
import { Loader2 } from "lucide-react"
4

5
function ServerSideTable() {
6
  const queryClient = useQueryClient()
7
  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 })
8
  // ... other state
9

10
  // Track prefetching state for UI feedback
11
  const [prefetchingState, setPrefetchingState] = useState<{
12
    next: boolean
13
    previous: boolean
14
  }>({ next: false, previous: false })
15
  const effectRunRef = useRef(0)
16

17
  // Prefetch next and previous pages
18
  useEffect(() => {
19
    const totalPages = Math.ceil(totalCount / pagination.pageSize)
20
    const currentPage = pagination.pageIndex
21
    const currentRun = ++effectRunRef.current
22

23
    // Reset prefetching state at the start of each effect run
24
    setTimeout(() => {
25
      if (currentRun === effectRunRef.current) {
26
        setPrefetchingState({ next: false, previous: false })
27
      }
28
    }, 0)
29

30
    // Prefetch next page if it exists
31
    if (currentPage + 1 < totalPages) {
32
      setTimeout(() => {
33
        if (currentRun === effectRunRef.current) {
34
          setPrefetchingState(prev => ({ ...prev, next: true }))
35
        }
36
      }, 0)
37

38
      queryClient
39
        .prefetchQuery({
40
          queryKey: [
41
            "products",
42
            currentPage + 1,
43
            pagination.pageSize,
44
            sorting,
45
            globalFilter,
46
            columnFilters,
47
            filterMode, // Include filterMode if you have filter modes
48
          ],
49
          queryFn: () =>
50
            fetchProducts({
51
              page: currentPage + 1,
52
              pageSize: pagination.pageSize,
53
              sorting,
54
              globalFilter,
55
              columnFilters,
56
            }),
57
          staleTime: 30000,
58
        })
59
        .then(() => {
60
          if (currentRun === effectRunRef.current) {
61
            setPrefetchingState(prev => ({ ...prev, next: false }))
62
          }
63
        })
64
        .catch(() => {
65
          if (currentRun === effectRunRef.current) {
66
            setPrefetchingState(prev => ({ ...prev, next: false }))
67
          }
68
        })
69
    }
70

71
    // Prefetch previous page if it exists
72
    if (currentPage > 0) {
73
      setTimeout(() => {
74
        if (currentRun === effectRunRef.current) {
75
          setPrefetchingState(prev => ({ ...prev, previous: true }))
76
        }
77
      }, 0)
78

79
      queryClient
80
        .prefetchQuery({
81
          queryKey: [
82
            "products",
83
            currentPage - 1,
84
            pagination.pageSize,
85
            sorting,
86
            globalFilter,
87
            columnFilters,
88
            filterMode, // Include filterMode if you have filter modes
89
          ],
90
          queryFn: () =>
91
            fetchProducts({
92
              page: currentPage - 1,
93
              pageSize: pagination.pageSize,
94
              sorting,
95
              globalFilter,
96
              columnFilters,
97
            }),
98
          staleTime: 30000,
99
        })
100
        .then(() => {
101
          if (currentRun === effectRunRef.current) {
102
            setPrefetchingState(prev => ({ ...prev, previous: false }))
103
          }
104
        })
105
        .catch(() => {
106
          if (currentRun === effectRunRef.current) {
107
            setPrefetchingState(prev => ({ ...prev, previous: false }))
108
          }
109
        })
110
    }
111

112
    // Cleanup function: reset state if effect re-runs
113
    return () => {
114
      setPrefetchingState({ next: false, previous: false })
115
    }
116
  }, [
117
    queryClient,
118
    pagination.pageIndex,
119
    pagination.pageSize,
120
    totalCount,
121
    sorting,
122
    globalFilter,
123
    columnFilters,
124
    filterMode, // Add filterMode to dependencies if you use it
125
  ])
126

127
  return (
128
    <div>
129
      {/* Show prefetching indicators */}
130
      {prefetchingState.next && (
131
        <div className="flex items-center gap-2 rounded-lg border bg-muted/30 p-2 text-xs">
132
          <Loader2 className="h-3 w-3 animate-spin" />
133
          <span className="text-muted-foreground">
134
            Prefetching next page...
135
          </span>
136
        </div>
137
      )}
138
      {prefetchingState.previous && (
139
        <div className="flex items-center gap-2 rounded-lg border bg-muted/30 p-2 text-xs">
140
          <Loader2 className="h-3 w-3 animate-spin" />
141
          <span className="text-muted-foreground">
142
            Prefetching previous page...
143
          </span>
144
        </div>
145
      )}
146

147
      {/* Table components */}
148
    </div>
149
  )
150
}

Key points about prefetching:

State tracking: Use a ref (effectRunRef) to track effect runs and prevent state updates from stale prefetch operations
State reset: Reset prefetching state at the start of each effect run to prevent stuck indicators
Error handling: Always reset state in .catch() handlers to prevent stuck indicators on errors
Cleanup: Reset state in the cleanup function when dependencies change

With prefetching enabled, navigation between pages feels instant because the data is already cached. The pagination buttons remain enabled during background fetching, allowing users to navigate to prefetched pages immediately. The prefetching indicators provide visual feedback so users know when background loading is happening.

Error Handling

TanStack Query provides error states and retry logic:

1
const { data, error, isError } = useQuery({
2
  queryKey: ['products', ...],
3
  queryFn: fetchProducts,
4
  retry: 1, // Retry failed requests once
5
})
6

7
if (isError) {
8
  return <ErrorDisplay error={error} />
9
}

State Management

This example uses React useState for state management. State does NOT persist across page refreshes. If you need URL state persistence, see the Server-Side Nuqs Table example.

1
function ServerSideTable() {
2
  // State management with useState
3
  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 })
4
  const [sorting, setSorting] = useState<SortingState>([])
5
  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
6
  const [globalFilter, setGlobalFilter] = useState<string | object>('')
7

8
  // Use TanStack Query for data fetching
9
  const { data, isLoading } = useQuery({
10
    queryKey: ['products', pagination, sorting, globalFilter, columnFilters],
11
    queryFn: () => fetchProducts({ ... }),
12
  })
13

14
  // ... rest of component
15
}

Manual Pagination, Sorting, and Filtering

When using server-side operations, you need to enable manual modes:

1
<DataTableRoot
2
  config={{
3
    manualPagination: true, // Server handles pagination
4
    manualSorting: true, // Server handles sorting
5
    manualFiltering: true, // Server handles filtering
6
    pageCount: totalPages, // Total pages from server
7
  }}
8
/>

Query Key Strategy

The query key should include all parameters that affect the data:

1
const queryKey = [
2
  "products", // Resource name
3
  pagination.pageIndex, // Page number
4
  pagination.pageSize, // Page size
5
  sorting, // Sort configuration
6
  globalFilter, // Search query
7
  columnFilters, // Column filters
8
]

This ensures that:

Different pages have separate cache entries
Changing filters invalidates and refetches data
Browser back/forward navigation uses cached data

Optimistic Updates

You can use TanStack Query mutations for optimistic updates:

1
import { useMutation, useQueryClient } from "@tanstack/react-query"
2

3
function useUpdateProduct() {
4
  const queryClient = useQueryClient()
5

6
  return useMutation({
7
    mutationFn: updateProduct,
8
    onMutate: async newProduct => {
9
      // Cancel outgoing refetches
10
      await queryClient.cancelQueries({ queryKey: ["products"] })
11

12
      // Snapshot previous value
13
      const previousProducts = queryClient.getQueryData(["products"])
14

15
      // Optimistically update
16
      queryClient.setQueryData(["products"], old => ({
17
        ...old,
18
        data: old.data.map(p => (p.id === newProduct.id ? newProduct : p)),
19
      }))
20

21
      return { previousProducts }
22
    },
23
    onError: (err, newProduct, context) => {
24
      // Rollback on error
25
      queryClient.setQueryData(["products"], context.previousProducts)
26
    },
27
    onSettled: () => {
28
      // Refetch after mutation
29
      queryClient.invalidateQueries({ queryKey: ["products"] })
30
    },
31
  })
32
}

When to Use

✅ Use Server-Side Table when:

Working with large datasets (thousands+ rows)
Data needs to be fetched from an API
You want automatic caching and background updates
You need request deduplication
You want optimistic updates
You need error handling and retry logic
You don’t need URL state persistence

❌ Consider other options when:

Working with small datasets (< 1000 rows) - use client-side filtering
Data is static or rarely changes - simple state management may suffice
You need URL state persistence - use Server-Side Nuqs Table
You need bookmarkable/shareable table views - use Server-Side Nuqs Table

Best Practices

Set appropriate stale times: Balance freshness with performance
Use query invalidation: Invalidate queries after mutations
Implement proper error handling: Show user-friendly error messages
Optimize query keys: Include all parameters that affect data
Use loading states: Show skeletons during initial load
Handle pagination: Reset to page 1 when filters change
Use placeholderData: keepPreviousData: Prevents UI jumps during pagination

Next Steps

Advanced Table - Learn about advanced filtering
Server-Side Nuqs Table - Add URL state persistence
TanStack Query Docs - Learn more about TanStack Query