On this page

Pagination

Learn how to use pagination in the data grid.

source

Overview

Pagination allows you to display a subset of data at a time which can be navigated through using the pagination controls.

By default, the pagination is handled on the client. This means you have to give the rows of all pages to the Data Grid. If your dataset is too big, and you want to fetch the pages on demand, you can create a custom action in a custom Toolbar action.

Implementing Pagination

You must opt-in to pagination by setting the initialState.pagination prop to either true or using a PaginationOptions object on the Data Grid. Doing so will display a static footer of pagination controls at the bottom of the grid.

Page Sizes

Note

The Data Grid comes built-int with a range of three predefined page sizes: 25, 50, and 100.

To enable custom page sizes, you need to provide a customRange value to the pagination options. This should be an Array of numbers representing the page sizes to display in the dropdown.

When this is provided, the Data Grid will use the first value in customRange as the initial page size.

Default Page

To set the default page, you can provide a defaultPage value to the pagination options.

Count

For server-side pagination where the total count is known beforehand, you can provide a count value to the pagination options.

This also means that the Data Grid will no longer automatically calculate the total number of pages based on the count and pageSize values (as per usual for server-side pagination).

Page Change Action

You can trigger a callback when the page change action is fired by providing a onPageChange prop to the Data Grid. This will recieve a details object with the current page number and page size.

This is useful for analytics or tracking page changes.

Note

If you plan on fetching more data on page change, the grid state will reset which includes the page state. This is due to the nature of client-side pagination.

Options

The pagination options accept the following properties:

Params	Required	Description
`defaultPage`	`false`	The index of the page to display by default.
`count`	`false`	The total number of items in the grid. This is useful for server-side pagination design
`pageSize`	`false`	The initial page size to use when the grid is first rendered. This must be one of the values in `customRange`.
`customRange`	`false`	An array of custom page sizes to display in the dropdown. This must include the `pageSize` value.

On this page

Overview
Implementing Pagination
Page Sizes
Default Page
Count
Page Change Action
Options
Edit this page on Github

On this page

Pagination

Learn how to use pagination in the data grid.

source

Overview

Pagination allows you to display a subset of data at a time which can be navigated through using the pagination controls.

Implementing Pagination

Page Sizes

Note

The Data Grid comes built-int with a range of three predefined page sizes: 25, 50, and 100.

To enable custom page sizes, you need to provide a customRange value to the pagination options. This should be an Array of numbers representing the page sizes to display in the dropdown.

When this is provided, the Data Grid will use the first value in customRange as the initial page size.

Note

If you plan on fetching more data on page change, the grid state will reset which includes the page state. This is due to the nature of client-side pagination.

Options

The pagination options accept the following properties:

Params	Required	Description
`defaultPage`	`false`	The index of the page to display by default.
`count`	`false`	The total number of items in the grid. This is useful for server-side pagination design
`pageSize`	`false`	The initial page size to use when the grid is first rendered. This must be one of the values in `customRange`.
`customRange`	`false`	An array of custom page sizes to display in the dropdown. This must include the `pageSize` value.

'use client'

import { DataGrid } from '@cerberus/data-grid'
import { useQuery } from '@cerberus/signals'
import { Stack } from 'styled-system/jsx'
import { queryEmployees } from '../api'
import { columns } from '../quick-start/columns.demo'

export function BasicDemo() {
  const data = useQuery(queryEmployees(1000))
  return (
    <Stack direction="column" h="20rem" w="3/4">
      <DataGrid columns={columns} data={data} initialState={{ pagination: true }} />
    </Stack>
  )
}

'use client'

import { DataGrid } from '@cerberus/data-grid'
import { Stack } from 'styled-system/jsx'
import { columns } from '../quick-start/columns.demo'
import { useFakeQuery } from '../quick-start/data'

export function ChangeDemo() {
  const data = useFakeQuery(100)

  return (
    <Stack direction="column" h="20rem" w="3/4">
      <DataGrid
        columns={columns}
        data={data}
        initialState={{ pagination: { pageSize: 25 } }}
        onPageChange={(details) => {
          console.log(details)
        }}
      />
    </Stack>
  )
}

'use client'

import { DataGrid } from '@cerberus/data-grid'
import { type PageDetails } from '@cerberus/react'
import { useQuery } from '@cerberus/signals'
import { useState, useTransition } from 'react'
import { Stack } from 'styled-system/jsx'
import { queryPaginatedEmployees } from '../api'
import { columns } from '../quick-start/columns.demo'

function useDeferredValue() {
  // Use native React state and transitions for loading state to override Suspsense
  const [current, setCurrent] = useState<PageDetails>({
    page: 1,
    pageSize: 25,
  })
  const [pending, startTransition] = useTransition()
  return {
    current,
    setCurrent,
    pending,
    startTransition,
  }
}

export function CountDemo() {
  const { current, setCurrent, pending, startTransition } = useDeferredValue()
  const data = useQuery(queryPaginatedEmployees(current))

  function handlePageChange(details: PageDetails) {
    console.log(details)
    startTransition(() => {
      setCurrent((prev) => ({ ...prev, ...details }))
    })
  }

  return (
    <Stack direction="column" h="20rem" w="3/4">
      <DataGrid
        columns={columns}
        data={data.data}
        initialState={{
          pagination: { count: data.pagination.count },
        }}
        onPageChange={handlePageChange}
        pending={pending}
      />
    </Stack>
  )
}

'use client'

import { DataGrid } from '@cerberus/data-grid'
import { Stack } from 'styled-system/jsx'
import { columns } from '../quick-start/columns.demo'
import { useFakeQuery } from '../quick-start/data'

export function PageDemo() {
  // Normally this would be from useQuery or a server-side API call
  const data = useFakeQuery(200)

  return (
    <Stack direction="column" h="20rem" w="3/4">
      <DataGrid
        columns={columns}
        data={data}
        initialState={{
          pagination: {
            defaultPage: 2,
          },
        }}
      />
    </Stack>
  )
}

'use client'

import { DataGrid } from '@cerberus/data-grid'
import { Stack } from 'styled-system/jsx'
import { columns } from '../quick-start/columns.demo'
import { useFakeQuery } from '../quick-start/data'

export function SizesDemo() {
  // Normally this would be from useQuery or a server-side API call
  const data = useFakeQuery(200)

  return (
    <Stack direction="column" h="20rem" w="3/4">
      <DataGrid
        columns={columns}
        data={data}
        initialState={{
          pagination: {
            customRange: [10, 20, 50],
          },
        }}
      />
    </Stack>
  )
}

import { type PaginationRootProps } from '@cerberus/react'

export type PaginationOptions = {
  defaultPage?: PaginationRootProps['defaultPage']
  pageSize?: PaginationRootProps['pageSize']
  customRange?: number[]
}