filters

Global Search

The global search filter allows users to search across all columns in the table. It provides a quick way to find specific data without needing to filter each column individually. It uses a fuzzy search by default, and highlights any directly matching text in the table.

Query Parameters

Current global search text is pushed to the URL as a query parameter search, so that users can share links to specific pre-searched data in a table. For example, navigating to ?search=cat will open the table with "cat" as the search term. When the search box is empty, the search query parameter is removed from the URL to keep it clean.

Custom Query Parameter Name

You can customize the query parameter name used for global search by setting tableOptions.queryKeys.search.

Generally we recommend keeping the default search value to ensure consistency across your application and user familiarity, however if you are using multiple tables on the same page you need to customize the query parameter names to avoid conflicts.

<DataTable tableOptions={{ queryKeys: { search: 'my-custom-table-search' } }} />

Disable Query Parameters

You can also disable query parameters for global search by setting tableOptions.queryKeys.search to false.

<DataTable tableOptions={{ queryKeys: { search: false } }} />

Column Filters

Column filters allow users to filter data in the table based on specific column values. Each column can have its own filter, enabling users to narrow down the data displayed according to their needs.

Filters are hidden by default, but can be shown by clicking the filter icon in the column header. On load, if any column has a filter defined in the query parameters the filter row will be shown automatically.

Text Filters

The default filter type is a text input that performs a fuzzy search, similar to the global search, only just for that specific column.

Unless filtering is disabled for a specific column, all columns will have text filters by default.

Select Filters

Often it is more useful to have a select dropdown as a filter, especially when the column has a limited set of known values. You can set the filterVariant property in the column definition to 'select' to enable a select filter for that column.

const columns: Columns<Cat> = [
  {
    accessorKey: 'age',
    filterVariant: 'select',
    header: 'Age',
  },
]

The select options will be generated automatically based on the unique values present in that column's dataset.

You can provide your set of options by using the filterSelectOptions property in the column definition.

const columns: Columns<Cat> = [
  {
    accessorKey: 'age',
    filterSelectOptions: [
      { label: '1', value: '1' },
      { label: '10', value: '10' },
    ],
    filterVariant: 'select',
    header: 'Age',
  },
]

Multi-Select Filters

You can also set the filterVariant property in the column definition to 'multi-select' to enable a multi-select filter for that column. This is arguably the most useful filter type, as it allows users to select multiple values to filter on. Otherwise, it works the same way as the select filter.

const columns: Columns<Cat> = [
  {
    accessorKey: 'breed',
    filterVariant: 'multi-select',
    header: 'Breed',
  },
]

Locked Column Filters

You can pre-filter and lock a column filter by setting the lockedFilter property in the column definition, this works for both text, select and multi-select filters.

const columns: Columns<Cat> = [
  {
    accessorKey: 'name',
    lockedFilter: 'M',
    header: 'Name',
  },
  {
    accessorKey: 'breed',
    filterVariant: 'multi-select',
    header: 'Breed',
    lockedFilter: ['Abyssinian', 'American Bobtail'],
  },
  {
    accessorKey: 'microchip',
    filterVariant: 'select',
    header: 'Microchip',
    lockedFilter: 'true',
  },
]

Disable Column Filters

You can disable a column filter by setting enableColumnFilter to false in the column definition.

const columns: Columns<Cat> = [
  {
    accessorKey: 'name',
    enableColumnFilter: false, // Disable filter for this column
    header: 'Name',
  },
  {
    accessorKey: 'age',
    header: 'Age',
    enableColumnFilter: false, // Disable filter for this column
  },
]

In the example below the three first columns have no filtering possibilities, note that the global search will still match on values in all columns, even those without column filters.

Query Params

Current column filter values are pushed to the URL as query parameters, so that users can share deep-links to specifically filtered data in a table.

Custom Query Parameter Name

You can customize the query parameter name used for a filter by setting the column id in the column definition.

const columns: Columns<Cat> = [
  {
    accessorKey: 'name',
    id: 'customNameFilter',
    header: 'Name',
  },
]

Unless explicitly set in the column definition, column ids will be the header value formatted as camelCase.

Generally we recommend keeping the default value to ensure consistency across your application and user familiarity, however if you are using multiple tables on the same page and they have columns with the same header names, you may need to customize the ids to avoid conflicts.

Disable Query Parameters