?page=2025

Pagination

Integer page index with server-side rendering

Rendering controls

Pagination controls (server-rendered)

Product list (server-rendered)

search-params.tsSource on GitHub

import { useQueryState, useQueryStates } from 'nuqs'
import {
  createLoader,
  createSerializer,
  type inferParserType,
  type Options,
  parseAsInteger,
  parseAsStringLiteral
} from 'nuqs/server'

export const renderingOptions = ['server', 'client'] as const
export type RenderingOptions = (typeof renderingOptions)[number]

const searchParams = {
  page: parseAsInteger.withDefault(1),
  renderOn: parseAsStringLiteral(renderingOptions).withDefault('server'),
  delay: parseAsInteger.withDefault(0)
}
export type PaginationSearchParams = inferParserType<typeof searchParams>

export const usePage = (options: Options = {}) =>
  useQueryState(
    'page',
    searchParams.page.withOptions({ ...options, shallow: false })
  )

export const usePaginationControls = () =>
  useQueryStates(searchParams, { shallow: false })

export const loadPagination = createLoader(searchParams)
export const getPaginatedLink = createSerializer(searchParams)

page.tsxSource on GitHub

import { Description } from '@/src/components/typography'
import { Separator } from '@/src/components/ui/separator'
import type { SearchParams } from 'nuqs/server'
import { Suspense } from 'react'
import { SourceOnGitHub } from '../_components/source-on-github'
import { getMetadata } from '../demos'
import { fetchProducts, pageCount } from './api'
import { ClientPaginationControls } from './pagination-controls.client'
import { ServerPaginationControls } from './pagination-controls.server'
import { ProductView } from './product'
import { RenderingControls } from './rendering-controls'
import { loadPagination, type PaginationSearchParams } from './search-params'

export const metadata = getMetadata('pagination')

type PageProps = {
  searchParams: Promise<SearchParams>
}

type PaginatedProps = {
  pagination: Promise<PaginationSearchParams>
}

export default async function PaginationDemoPage({ searchParams }: PageProps) {
  // Allow nested RSCs to access the search params (in a type-safe way)
  const pagination = loadPagination(searchParams)
  return (
    <>
      <h1>{metadata.title}</h1>
      <Description>{metadata.description}</Description>
      <h2>Rendering controls</h2>
      <Suspense>
        <RenderingControls />
      </Suspense>
      <Separator className="my-8" />
      <Suspense>
        <PaginationRenderer pagination={pagination} />
      </Suspense>
      <Suspense>
        <ProductSection pagination={pagination} />
      </Suspense>
      <SourceOnGitHub path="pagination/search-params.ts" />
      <SourceOnGitHub path="pagination/page.tsx" />
      <SourceOnGitHub path="pagination/pagination-controls.server.tsx" />
      <SourceOnGitHub path="pagination/pagination-controls.client.tsx" />
    </>
  )
}

async function PaginationRenderer({ pagination }: PaginatedProps) {
  const { renderOn } = await pagination
  return (
    <>
      <h2>
        Pagination controls{' '}
        <small className="text-sm font-medium text-zinc-500">
          ({renderOn}-rendered)
        </small>
      </h2>
      {renderOn === 'server' && (
        <ServerPaginationControls
          numPages={pageCount}
          pagination={pagination}
        />
      )}
      <Suspense key="client">
        {renderOn === 'client' && (
          <ClientPaginationControls numPages={pageCount} />
        )}
      </Suspense>
    </>
  )
}

async function ProductSection({ pagination }: PaginatedProps) {
  const { page, delay } = await pagination
  const products = await fetchProducts(page, delay)
  return (
    <section>
      <h2>
        Product list{' '}
        <small className="text-sm font-medium text-zinc-500">
          (server-rendered)
        </small>
      </h2>
      {products.map(product => (
        <ProductView product={product} key={product.id} />
      ))}
    </section>
  )
}

pagination-controls.server.tsxSource on GitHub

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNextLink,
  PaginationPreviousLink
} from '@/src/components/ui/pagination'
import { cn } from '@/src/lib/utils'
import { getPaginatedLink, PaginationSearchParams } from './search-params'

type PaginationControlsProps = {
  numPages: number
  pagination: Promise<PaginationSearchParams>
}

// Use <Link> components to navigate between pages
export async function ServerPaginationControls({
  numPages,
  pagination
}: PaginationControlsProps) {
  const { page, delay, renderOn } = await pagination
  function pageURL(page: number) {
    return getPaginatedLink('/playground/pagination', {
      page,
      delay,
      renderOn
    })
  }
  return (
    <Pagination className="not-prose items-center gap-2">
      <PaginationContent>
        <PaginationItem>
          <PaginationPreviousLink
            href={pageURL(page - 1)}
            disabled={page === 1}
            scroll={false}
          />
        </PaginationItem>
        {Array.from({ length: numPages }, (_, i) => (
          <PaginationItem key={i}>
            <PaginationLink
              href={pageURL(i + 1)}
              isActive={page === i + 1}
              scroll={false}
            >
              {i + 1}
            </PaginationLink>
          </PaginationItem>
        ))}
        <PaginationItem>
          <PaginationNextLink
            disabled={page === numPages}
            href={pageURL(page + 1)}
            scroll={false}
          />
        </PaginationItem>
      </PaginationContent>
      <div
        aria-label={'Loading status unavailable on the server'}
        className={cn('h-2 w-2 rounded-full bg-zinc-500')}
      />
    </Pagination>
  )
}

pagination-controls.client.tsxSource on GitHub

'use client'

import {
  Pagination,
  PaginationButton,
  PaginationContent,
  PaginationItem,
  PaginationNext,
  PaginationPrevious
} from '@/src/components/ui/pagination'
import { cn } from '@/src/lib/utils'
import React from 'react'
import { usePage } from './search-params'

type PaginationControlsProps = {
  numPages: number
}

// Use client-side hooks to update the page number
// and observe the loading state
export function ClientPaginationControls({
  numPages
}: PaginationControlsProps) {
  const [isLoading, startTransition] = React.useTransition()
  const [page, setPage] = usePage({ startTransition })
  return (
    <Pagination className="not-prose items-center gap-2">
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious
            disabled={page === 1}
            onClick={() => setPage(p => Math.max(1, p - 1))}
          />
        </PaginationItem>
        {Array.from({ length: numPages }, (_, i) => (
          <PaginationItem key={i}>
            <PaginationButton
              isActive={page === i + 1}
              onClick={() => setPage(i + 1)}
            >
              {i + 1}
            </PaginationButton>
          </PaginationItem>
        ))}
        <PaginationItem>
          <PaginationNext
            disabled={page === numPages}
            onClick={() => setPage(p => Math.min(numPages, p + 1))}
          />
        </PaginationItem>
      </PaginationContent>
      <div
        aria-label={isLoading ? 'Loading' : 'Idle'}
        aria-live={isLoading ? 'polite' : undefined}
        className={cn(
          'h-2 w-2 rounded-full bg-green-500',
          isLoading && 'animate-pulse bg-amber-500'
        )}
      />
    </Pagination>
  )
}