Data Grid Quickstart

import { DataGrid, createColumnHelper } from '@cerberus/data-grid'

Usage

Loading example...

Understanding the Data Grid

The Data Grid is a complex component that provides a wide range of features for displaying and interacting with data. It includes a variety of helpers to create an enhanced developer experience.

Step 1: The Data

The DataGrid accepts any form of data structures. Data is not what drives the component - defined columns are. All that matters for your data is that it is typed.

Loading example...

Step 2: Setup Columns

Columns are the engine that run the Data Grid.

Columns are defined using the createColumnHelper. This will provide a strictly typed interface for defining individual columns.

Pass in your data type to the createColumnHelper function and build your columns.

Loading example...

Creating Columns

Once you have setup your helper singleton, you can start building columns.

There are three methods available to create columns:

display: Non-interactive columns.
accessor: Interactive columns that utilize the features options.
accessorFn: Interactive columns that allow your to define custom logic for rendering cells.

Loading example...

You can learn more about the columns in on the Columns page.

Use the DataGrid

The final step is to add the DataGrid component to your application. You simply pass in the data, columns, and any other feature-related props.

Note

For contstrained layouts (seen in the demo preview), we recommend wrapping the DataGrid in a container that has a strict height defined.

Loading example...

The next pages cover each feature in detail.

import { DataGrid, createColumnHelper } from '@cerberus/data-grid'

Usage

Loading example...

Understanding the Data Grid

The Data Grid is a complex component that provides a wide range of features for displaying and interacting with data. It includes a variety of helpers to create an enhanced developer experience.

Step 1: The Data

The DataGrid accepts any form of data structures. Data is not what drives the component - defined columns are. All that matters for your data is that it is typed.

export type Employee = {
  id: number
  firstName: string
  lastName: string
  email: string
  status: 'active' | 'inactive' | 'on_leave'
  salary: number
  department: {
    name: string
    code: string
  }
  lastLogin: string
}

Loading example...

Step 2: Setup Columns

Columns are the engine that run the Data Grid.

Columns are defined using the createColumnHelper. This will provide a strictly typed interface for defining individual columns.

Pass in your data type to the createColumnHelper function and build your columns.

import { createColumnHelper } from '@cerberus/react/data-grid'
import { type Employee } from './data.demo'

export const columnHelper = createColumnHelper<Employee>()

Loading example...

Creating Columns

Once you have setup your helper singleton, you can start building columns.

There are three methods available to create columns:

display: Non-interactive columns.
accessor: Interactive columns that utilize the features options.
accessorFn: Interactive columns that allow your to define custom logic for rendering cells.

'use client'

import { Edit } from '@carbon/icons-react'
import { Format, IconButton, Tag, TagProps, Text } from '@cerberus/react/react'
import { HStack, VStack } from 'styled-system/jsx'
import { columnHelper } from './helper.demo'

export const columns = [
  // A. "ID" Column that can be pinned and sorted
  columnHelper.accessor('id', {
    header: 'ID',
    width: 80,
    features: {
      pinning: {
        defaultPosition: 'left',
      },
      sort: true,
    },
    cell: ({ value }) => <Text>#{value}</Text>,
  }),

  // B. Derived Accessor (Function)
  // We combine First + Last name for sorting/filtering, but render custom UI
  columnHelper.accessorFn((row) => `${row.firstName} ${row.lastName}`, {
    id: 'fullName',
    header: 'Employee',
    width: 250,
    features: {
      sort: true,
      filter: true,
    },
    cell: ({ row, value }) => (
      <VStack alignItems="flex-start" gap="0">
        <Text textStyle="body-md">{value}</Text>
        <Text color="page.text.100" textStyle="label-sm">
          {row.email}
        </Text>
      </VStack>
    ),
  }),

  // C. Deep Accessor (Nested Object) using a plain text string for the cell
  columnHelper.accessorFn((row) => row.department.name, {
    id: 'department',
    header: 'Department',
    features: { sort: true },
  }),

  // D. Formatting (Numeric Sort, String Display)
  columnHelper.accessor('salary', {
    header: 'Salary',
    minWidth: 135,
    features: { sort: true }, // ✅ Sorts numerically (100 before 500)
    // We format the visual ONLY. The underlying data remains a number.
    cell: ({ value }) => (
      <Format.Number value={value} style="currency" currency="USD" />
    ),
  }),

  // E. Status Badge
  columnHelper.accessor('status', {
    header: 'Status',
    width: 110,
    features: {
      pinning: true,
    },
    cell: ({ value }) => {
      const palette: Record<string, TagProps['palette']> = {
        active: 'success',
        inactive: 'page',
        on_leave: 'info',
      }
      return <Tag palette={palette[value]}>{value.replace('_', ' ').toUpperCase()}</Tag>
    },
  }),

  // F. Display Column (Right Pinned Actions)
  columnHelper.display({
    id: 'actions',
    header: 'Actions',
    width: 125,
    features: {
      pinning: true,
    },
    cell: () => (
      <HStack justify="center" w="full">
        <IconButton ariaLabel="View more options">
          <Edit />
        </IconButton>
      </HStack>
    ),
  }),
]

Loading example...

You can learn more about the columns in on the Columns page.

Use the DataGrid

The final step is to add the DataGrid component to your application. You simply pass in the data, columns, and any other feature-related props.

Note

For contstrained layouts (seen in the demo preview), we recommend wrapping the DataGrid in a container that has a strict height defined.

Loading example...

The next pages cover each feature in detail.