Server-Side Nuqs Table

Server-side pagination, sorting, and filtering with TanStack Query and URL state persistence using nuqs.

Loading products from server...

Product Name	Category	Brand	Price	Stock	Rating	In Stock	Release Date

Server-Side Table State (URL Synced)

All state is persisted in the URL and survives page refreshes. Data is fetched from a mocked API with delays using TanStack Query.

Current URL:No query params

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:

{}

URL Filters (AND logic):

[]

Inline Filters:

[]

Search Query:

""

💡 Tip: Try adding filters, sorting, or changing pages, then copy the URL and paste it in a new tab. All your table state will be preserved! The data is fetched server-side with TanStack Query caching.

Introduction

The Server-Side Nuqs Table demonstrates server-side pagination, sorting, and filtering using TanStack Query for efficient data fetching, caching, and state management, combined with nuqs for URL state persistence. This example shows how to handle large datasets by fetching data from a server with automatic caching, background updates, and request deduplication, while maintaining all table state in the URL for bookmarkable and shareable views.

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 nuqs

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.
nuqs enables URL state persistence, making table views bookmarkable and shareable.

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 + Nuqs, you need to wrap your app with both QueryClientProvider and NuqsAdapter. 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
import { NuqsAdapter } from "nuqs/adapters/next/app"
3

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

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

Next.js Pages Router

Wrap <Component> in pages/_app.tsx:

1
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
2
import { NuqsAdapter } from "nuqs/adapters/next/pages"
3

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

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

React SPA (Vite, CRA, etc.)

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

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

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

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

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 { useQuery } from "@tanstack/react-query"
2
import type { SortingState, ColumnFiltersState } from "@tanstack/react-table"
3

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

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

31
  const products = data?.data ?? []
32
  const totalCount = data?.total ?? 0
33

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

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 ServerSideNuqsTable() {
6
  const queryClient = useQueryClient()
7
  const [urlParams, setUrlParams] = useQueryStates(tableStateParsers)
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 / urlParams.pageSize)
20
    const currentPage = urlParams.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
            urlParams.pageSize,
44
            urlParams.sort,
45
            urlParams.globalFilter,
46
            urlParams.filters,
47
            urlParams.filterMode,
48
          ],
49
          queryFn: () =>
50
            fetchProducts({
51
              page: currentPage + 1,
52
              pageSize: urlParams.pageSize,
53
              sorting: urlParams.sort,
54
              globalFilter: urlParams.globalFilter,
55
              columnFilters: urlParams.filters,
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
            urlParams.pageSize,
85
            urlParams.sort,
86
            urlParams.globalFilter,
87
            urlParams.filters,
88
            urlParams.filterMode,
89
          ],
90
          queryFn: () =>
91
            fetchProducts({
92
              page: currentPage - 1,
93
              pageSize: urlParams.pageSize,
94
              sorting: urlParams.sort,
95
              globalFilter: urlParams.globalFilter,
96
              columnFilters: urlParams.filters,
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
    urlParams.pageIndex,
119
    urlParams.pageSize,
120
    urlParams.sort,
121
    urlParams.globalFilter,
122
    urlParams.filters,
123
    urlParams.filterMode,
124
    totalCount,
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
}

URL State Management with nuqs

This example uses nuqs to persist all table state in the URL, making table views bookmarkable and shareable. The state includes:

Pagination (page index and page size)
Sorting configuration
Column filters (standard and inline modes)
Global search/filter
Column visibility
Filter mode (standard vs inline)

URL State Parsers

Define parsers for each state variable:

1
import { parseAsInteger, parseAsJson, parseAsString } from "nuqs"
2
import type { SortingState } from "@tanstack/react-table"
3
import type { ExtendedColumnFilter } from "@/components/niko-table/types"
4

5
const tableStateParsers = {
6
  pageIndex: parseAsInteger.withDefault(0),
7
  pageSize: parseAsInteger.withDefault(10),
8
  sort: parseAsJson<SortingState>(value => value as SortingState).withDefault(
9
    [],
10
  ),
11
  filters: parseAsJson<ExtendedColumnFilter<Product>[]>(
12
    value => value as ExtendedColumnFilter<Product>[],
13
  ).withDefault([]),
14
  search: parseAsString.withDefault(""),
15
  globalFilter: parseAsJson<
16
    string | { filters: unknown[]; joinOperator: string }
17
  >(value => {
18
    if (value && typeof value === "object" && "filters" in value) {
19
      return value as { filters: unknown[]; joinOperator: string }
20
    }
21
    if (typeof value === "string") {
22
      return value
23
    }
24
    return ""
25
  }).withDefault(""),
26
  columnVisibility: parseAsJson<VisibilityState>(
27
    value => value as VisibilityState,
28
  ).withDefault({}),
29
  inlineFilters: parseAsJson<ExtendedColumnFilter<Product>[]>(
30
    value => value as ExtendedColumnFilter<Product>[],
31
  ).withDefault([]),
32
  filterMode: parseAsString.withDefault("standard"),
33
}

Using useQueryStates

The useQueryStates hook provides URL state management:

1
import { useQueryStates } from "nuqs"
2

3
function ServerSideTable() {
4
  const [urlParams, setUrlParams] = useQueryStates(tableStateParsers, {
5
    urlKeys: {
6
      pageIndex: "page",
7
      pageSize: "perPage",
8
      sort: "sort",
9
      filters: "filters",
10
      search: "search",
11
      globalFilter: "global",
12
      columnVisibility: "cols",
13
      inlineFilters: "inline",
14
      filterMode: "mode",
15
    },
16
    history: "replace",
17
    scroll: false,
18
    shallow: true,
19
  })
20

21
  // Use urlParams for table state
22
  const pagination = useMemo(
23
    () => ({
24
      pageIndex: urlParams.pageIndex,
25
      pageSize: urlParams.pageSize,
26
    }),
27
    [urlParams.pageIndex, urlParams.pageSize],
28
  )
29

30
  // Update URL when state changes
31
  const handlePaginationChange = useCallback(
32
    (updater: Updater<PaginationState>) => {
33
      const newPagination =
34
        typeof updater === "function" ? updater(pagination) : updater
35
      void setUrlParams({
36
        pageIndex: newPagination.pageIndex,
37
        pageSize: newPagination.pageSize,
38
      })
39
    },
40
    [pagination, setUrlParams],
41
  )
42

43
  // ... rest of component
44
}

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 + Nuqs 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 want URL state persistence for bookmarkable and shareable table views
You need table state to survive page refreshes

❌ 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 don’t need URL state persistence - use a simpler server-side implementation without nuqs

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

Next Steps

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