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

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.

The Data Grid automatically calculates the total number of pages based on the count and pageSize values when using client-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.

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

Edit this page on Github

Pagination

Learn how to use pagination in the data grid.

source

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.

Cerberus Design System | Docs

'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 BasicDemo() {
  // Normally this would be from useQuery or a server-side API call
  const data = useFakeQuery(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 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>
  )
}

'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 { useState } from 'react'
import { Stack } from 'styled-system/jsx'
import { columns } from '../quick-start/columns.demo'
import { useFakeQuery } from '../quick-start/data'

const count = 1000
const maxPageSize = 100

export function CountDemo() {
  const [current, setCurrent] = useState<number>(maxPageSize)

  // Normally this would be from useQuery or a server-side API call
  const data = useFakeQuery(current)

  return (
    <Stack direction="column" h="20rem" w="3/4">
      <DataGrid
        columns={columns}
        data={data}
        initialState={{
          pagination: { count },
        }}
        onPageChange={(details) => {
          console.log(details)
          const currentPages = Math.ceil(data.length / details.pageSize)
          const hasEnough = details.page + 1 <= currentPages
          if (hasEnough) return
          setCurrent((prev) => prev + maxPageSize)
        }}
      />
    </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>
  )
}

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

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