Filtering

Overview

Filtering allows users to view a subset of data based on criteria. There are three ways for a user to filter:

Single-column filtering: Clicking the "Filter" option from the feature menu when the column has opted into filtering.
Multi-column filtering: Following option 1 for any additional column
Global filtering: Utilizing the setGlobalFilter action from the Data Grid Context.

Active Actions

Once a filter is active, the user can:

Edit filters: Clicking the added "Edit filter" icon button that displays in the column header that has the active filter.
Clear filters: Clicking the "Clear Filter" option in the column feature menu.

Loading example...

Implementing column filtering

You must opt-in to column filtering by setting the features.filter prop to true or passing in a custom filter function. Doing so will display the filter option in the column menu.

Loading example...

Multi-column Filtering

Multi-column filtering is enabled by default. The user simply selects another column to filter in addition to any other column that is actively filtered.

Global Filtering

You can globally filter the Grid by utilizing the setGlobalFilter action in any slot component you provide.

In this example, we create a custom Toolbar that filters the grid globally on input.

Loading example...

Custom Comparator

A comparator determines how two cell values should be filtered. The default comparator uses the vanilla JavaScript basic comparison from the Operator provided.

To provide a custom comparator, you can pass a function as the features.filter option.

The snippet below is the same comparator we are using for all the demos on this page.

Loading example...

Operators

The Data Grid provides an OPERATORS constant which is used to ensure consistency across any filter-based approach you may use.

Loading example...

Options

The filter feature accepts either a boolean or a custom filter function that provides the following arguments:

Params	Type	Description
`row`	`TData`	The row of the grid comparing the filter.
`columnId`	`string`	The columnId the filter is applied to.
`filterValue`	`unknown`	The value provided to the filter.

Overview

Filtering allows users to view a subset of data based on criteria. There are three ways for a user to filter:

Single-column filtering: Clicking the "Filter" option from the feature menu when the column has opted into filtering.
Multi-column filtering: Following option 1 for any additional column
Global filtering: Utilizing the setGlobalFilter action from the Data Grid Context.

Active Actions

Once a filter is active, the user can:

Edit filters: Clicking the added "Edit filter" icon button that displays in the column header that has the active filter.
Clear filters: Clicking the "Clear Filter" option in the column feature menu.

Loading example...

Implementing column filtering

You must opt-in to column filtering by setting the features.filter prop to true or passing in a custom filter function. Doing so will display the filter option in the column menu.

Loading example...

Multi-column Filtering

Multi-column filtering is enabled by default. The user simply selects another column to filter in addition to any other column that is actively filtered.

Global Filtering

You can globally filter the Grid by utilizing the setGlobalFilter action in any slot component you provide.

In this example, we create a custom Toolbar that filters the grid globally on input.

Loading example...

Custom Comparator

A comparator determines how two cell values should be filtered. The default comparator uses the vanilla JavaScript basic comparison from the Operator provided.

To provide a custom comparator, you can pass a function as the features.filter option.

The snippet below is the same comparator we are using for all the demos on this page.

import { VStack } from '@/styled-system/jsx'
import { Text } from '@cerberus/react/react'
import { columnHelper } from '../col-defs/employees'

export const columns = [
  columnHelper.accessorFn((row) => `${row.firstName} ${row.lastName}`, {
    id: 'fullName',
    header: 'Employee',
    minWidth: 300,
    features: {
      sort: true,
      filter: (row, _colId, val) => {
        // 1. Bail early if the user cleared the input
        if (!val) return true
        // 2. Normalize the search term to lowercase
        const searchTerm = String(val).toLowerCase()
        // 3. Reconstruct the string we want to search
        const fullName = `${row.firstName} ${row.lastName}`.toLowerCase()
        // 4. Grab the email from the raw row data
        const email = String(row.email).toLowerCase()
        // 5. Match against BOTH
        // If they type "john", it matches the name.
        // If they type "@company.com", it matches the email.
        return fullName.includes(searchTerm) || email.includes(searchTerm)
      },
    },
    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>
    ),
  }),
]

Loading example...

Operators

The Data Grid provides an OPERATORS constant which is used to ensure consistency across any filter-based approach you may use.

import { type FilterOperator } from '@cerberus/react/data-grid'

export const OPERATORS: Record<FilterOperator, FilterOperator> = {
  contains: 'contains',
  equals: 'equals',
  starts_with: 'starts_with',
  ends_with: 'ends_with',
  greater_than: 'greater_than',
  less_than: 'less_than',
  between: 'between',
  includes_some: 'includes_some',
}

Loading example...

Options

The filter feature accepts either a boolean or a custom filter function that provides the following arguments:

Params	Type	Description
`row`	`TData`	The row of the grid comparing the filter.
`columnId`	`string`	The columnId the filter is applied to.
`filterValue`	`unknown`	The value provided to the filter.