Column Filtering Feature Guide

Filtering is one of the most powerful features of Material React Table and is enabled by default. There is a lot of flexibility and customization available here. Whether you want to customize the powerful client-side filtering already built in or implement your own server-side filtering, Material React Table has got you covered.

Relevant Props

#	Type	Default Value	More Info Links
1	Array<MRT_FilterOption \| string> \| null		MRT Column Filtering Docs

2	boolean	false	MRT Column Filtering Docs

3	boolean	true	MRT Column Filtering Docs

4	boolean	true	TanStack Filters Docs

5	Record<string, FilterFn>		TanStack Table Filters Docs

6	boolean	false	TanStack Filtering Docs

7	() => Map<any, number>		TanStack Table Filters Docs

8	() => RowModel<TData>		TanStack Table Filters Docs

9	() => Map<any, number>		TanStack Table Filters Docs

10	() => RowModel<TData>		TanStack Table Filters Docs

11	boolean		TanStack Table Filters Docs

12	number	100	TanStack Table Filtering Docs

13	TextFieldProps \| ({ table, column, rangeFilterIndex}) => TextFieldProps		Material UI TextField Props

14	OnChangeFn<{ [key: string]: MRT_FilterOption }>

15	OnChangeFn<ColumnFiltersState>		TanStack Table Filter Docs

16	OnChangeFn<boolean>

17	({ column, internalFilterOptions, onSelectFilterMode, table }) => ReactNode[]

Relevant Column Options

#	Type	Default Value	More Info Links
1	({ column, header, table }) => ReactNode		MRT Column Filtering Docs

2	Array<string>

3	boolean		MRT Column Filtering Docs

4	boolean		MRT Column Filtering Docs

5	MRT_FilterFn	fuzzy

6	Array<{ text: string; value: string }>

7	'text' \| 'select' \| 'multi-select' \| 'range'	text

8	TextFieldProps \| ({ column, rangeFilterIndex, table }) => TextFieldProps		Material UI TextField Props

9

Relevant State Options

#	Type	Default Value	More Info Links
1	{ [key: string]: MRT_FilterFn }

2	Array<{id: string, value: unknown}>	{}	TanStack Table Filters Docs

3	boolean	false

Disable Filtering Features

Various subsets of filtering features can be disabled. If you want to disable filtering completely, you can set the enableColumnFilters prop to false to remove all filters from each column. Alternatively, enableColumnFilter can be set to false for individual columns.

enableFilters can be set to false to disable both column filters and the global search filter.

Demo

Open Stackblitz Open Code Sandbox Open on GitHub

ID	First Name	Middle Name	Last Name
1	Hugh	Jay	Mungus
2	Leroy	Leroy	Jenkins

Source Code

1import React, { FC, useMemo } from 'react';
2import MaterialReactTable, { MRT_ColumnDef } from 'material-react-table';
3
4const Example: FC = () => {
5  const columns = useMemo(
6    () =>
7      [
8        {
9          accessorKey: 'id',
10          enableColumnFilter: false, // could disable just this column's filter
11          header: 'ID',
12        },
13        //column definitions...
14        {
15          accessorKey: 'firstName',
16          header: 'First Name',
17        },
18        {
19          accessorKey: 'middleName',
20          header: 'Middle Name',
21        },
22        {
23          accessorKey: 'lastName',
24          header: 'Last Name',
25        },
26        
27      ] as MRT_ColumnDef<typeof data[0]>[],
28    [],
29  );
30
31  const data = useMemo(
32    //data definitions...
33    () => [
34      {
35        id: 1,
36        firstName: 'Hugh',
37        middleName: 'Jay',
38        lastName: 'Mungus',
39      },
40      {
41        id: 2,
42        firstName: 'Leroy',
43        middleName: 'Leroy',
44        lastName: 'Jenkins',
45      },
46    ],
47    [],
48    
49  );
50
51  return (
52    <MaterialReactTable
53      columns={columns}
54      data={data}
55      enableColumnFilters={false} //disable all column filters
56    />
57  );
58};
59
60export default Example;
61

Filter Variants

Material React Table has several built-in filter variants for advanced filtering. These can be specified on a per-column basis using the filterVariant option. The following variants are available:

'text' - shows the default text field
'select' - shows a select dropdown with the options specified in filterSelectOptions
'multi-select' - shows a select dropdown with the options specified in filterSelectOptions and allows multiple selections with checkboxes
'range - shows min and max text fields for filtering a range of values
'checkbox' - shows a checkbox for filtering by 'true' or 'false' values (Strings)

Demo

Open Stackblitz Open Code Sandbox Open on GitHub

Account Status Filter by Account Status	Name	Age	City Filter by City	State Filter by State
Active	Tanner Linsley	42	San Francisco	California
Active	Kevin Vandy	51	Richmond	Virginia
Inactive	John Doe	27	Riverside	South Carolina
Active	Jane Doe	32	San Francisco	California
Inactive	John Smith	42	Los Angeles	California
Active	Jane Smith	51	Blacksburg	Virginia
Inactive	Samuel Jackson	27	New York	New York

Source Code

1import React, { FC, useMemo } from 'react';
2import MaterialReactTable, { MRT_ColumnDef } from 'material-react-table';
3import { citiesList, data, Person, usStateList } from './makeData';
4
5const Example: FC = () => {
6  const columns = useMemo<MRT_ColumnDef<Person>[]>(
7    () => [
8      {
9        header: 'Account Status',
10        accessorFn: (originalRow) => (originalRow.isActive ? 'true' : 'false'), //must be strings
11        id: 'isActive',
12        filterVariant: 'checkbox',
13        Cell: ({ cell }) =>
14          cell.getValue() === 'true' ? 'Active' : 'Inactive',
15        size: 220,
16      },
17      {
18        accessorKey: 'name',
19        header: 'Name',
20        filterVariant: 'text', // default
21      },
22      {
23        accessorKey: 'age',
24        header: 'Age',
25        filterVariant: 'range',
26        filterFn: 'betweenInclusive', // use betweenInclusive instead of between
27      },
28      {
29        accessorKey: 'city',
30        header: 'City',
31        filterVariant: 'select',
32        filterSelectOptions: citiesList,
33      },
34      {
35        accessorKey: 'state',
36        header: 'State',
37        filterVariant: 'multi-select',
38        filterSelectOptions: usStateList,
39      },
40    ],
41    [],
42  );
43
44  return (
45    <MaterialReactTable
46      columns={columns}
47      data={data}
48      initialState={{ showColumnFilters: true }}
49    />
50  );
51};
52
53export default Example;
54

Custom Filter Functions

You can specify either a pre-built filterFn that comes with Material React Table or pass in your own custom filter functions.

Custom Filter Functions Per Column

By default, Material React Table uses a fuzzy filtering algorithm based on the popular match-sorter library from Kent C. Dodds. However, Material React Table also comes with numerous other filter functions that you can specify per column in the filterFn column options.

Pre-built MRT Filter Functions

Pre-built filter functions from Material React table include between, betweenInclusive, contains, empty, endsWith, equals, fuzzy, greaterThan, greaterThanOrEqualTo, lessThan, lessThanOrEqualTo, notEmpty, notEquals, and startsWith. View these algorithms here

Pre-built TanStack Table Filter Functions

Pre-built filter functions from TanStack Table include includesString, includesStringSensitive, equalsString, equalsStringSensitive, arrIncludes, arrIncludesAll, arrIncludesSome, weakEquals, and inNumberRange. View more information about these algorithms in the TanStack Table Filter docs.

You can specify either a pre-built filter function, from Material React Table or TanStack Table, or you can even specify your own custom filter function in the filterFn column option.

const columns = [
  {
    accessorKey: 'firstName',
    header: 'First Name',
    // using a prebuilt filter function from Material React Table
    filterFn: 'startsWith',
  },
  {
    accessorKey: 'middleName',
    header: 'Middle Name',
    // using a prebuilt filter function from TanStack Table
    filterFn: 'includesStringSensitive',
  },
  {
    accessorKey: 'lastName',
    header: 'Last Name',
    // custom filter function
    filterFn: (row, id, filterValue) =>
      row.getValue(id).startsWith(filterValue),
  },
];

If you provide a custom filter function, it must have the following signature:

(row: Row<TData>, id: string, filterValue: string | number) => boolean;

This function will be used to filter 1 row at a time and should return a boolean indicating whether or not that row passes the filter.

Add Custom Filter Functions

You can add custom filter functions to the filterFns prop. These will be available to all columns to use. The filterFn prop on a column will override any filter function with the same name in the filterFns prop.

const columns = [
  {
    accessorKey: 'name',
    header: 'Name',
    filterFn: 'customFilterFn',
  },
];

return (
  <MaterialReactTable
    data={data}
    columns={columns}
    filterFns={{
      customFilterFn: (row, id, filterValue) => {
        return row.customField === value;
      },
    }}
  />
);

Filter Modes

Enable Column Filter Modes (Filter Switching)

If you want to let the user switch between multiple different filter modes from a drop-down menu on the Filter Textfield, you can enable that with the enableColumnFilterModes prop or column option. This will enable the filter icon in the filter text field to open a drop-down menu with the available filter modes when clicked.

<MaterialReactTable columns={columns} data={data} enableColumnFilterModes />

Customize Filter Modes

You can narrow down the available filter mode options by setting the columnFilterModeOptions prop or a column specific columnFilterModeOptions option.

const columns = [
  {
    accessorKey: 'firstName',
    header: 'First Name',
    columnFilterModeOptions: ['fuzzy', 'contains', 'startsWith'],
  },
  {
    accessorKey: 'age',
    header: 'Age',
    columnFilterModeOptions: ['between', 'lessThan', 'greaterThan'],
  },
  }
]

You can also render custom menu items in the filter mode drop-down menu by setting the renderColumnFilterModeMenuItems prop or column option. This option is a function that takes in the column and returns an array of MenuItem components. This is useful if you want to add custom filter modes that are not included in Material React Table, or if you just want to render the menu in your own custom way

const columns = [
  {
    accessorKey: 'firstName',
    header: 'First Name',
    renderColumnFilterModeMenuItems: ({ column, onSelectFilterMode }) => [
      <MenuItem
        key="startsWith"
        onClick={() => onSelectFilterMode('startsWith')}
      >
        Start With
      </MenuItem>,
      <MenuItem
        key="endsWith"
        onClick={() => onSelectFilterMode('yourCustomFilterFn')}
      >
        Your Custom Filter Fn
      </MenuItem>,
    ],
  },
];

return (
  <MaterialReactTable
    columns={columns}
    data={data}
    enableColumnFilterModes
    // renderColumnFilterModeMenuItems could go here if you want to apply to all columns
  />
);

Demo

Open Stackblitz Open Code Sandbox Open on GitHub

ID	First Name Filter Mode: Fuzzy	Middle Name	Last Name Filter Mode: Fuzzy	Age Filter Mode: Between
1	Hugh	Jay	Mungus	42
2	Leroy	Leroy	Jenkins	51
3	Candice	Denise	Nutella	27
4	Micah	Henry	Johnson	32

Source Code

1import React, { FC, useMemo } from 'react';
2import MaterialReactTable, { MRT_ColumnDef } from 'material-react-table';
3import { MenuItem } from '@mui/material';
4import { data, Person } from './makeData';
5
6const Example: FC = () => {
7  const columns = useMemo<MRT_ColumnDef<Person>[]>(
8    () => [
9      {
10        accessorKey: 'id',
11        enableColumnFilterModes: false, //disable changing filter mode for this column
12        filterFn: 'equals', //set filter mode to equals
13        header: 'ID',
14      },
15      {
16        accessorKey: 'firstName', //normal, all filter modes are enabled
17        header: 'First Name',
18      },
19      {
20        accessorKey: 'middleName',
21        enableColumnFilterModes: false, //disable changing filter mode for this column
22        filterFn: 'startsWith', //even though changing the mode is disabled, you can still set the default filter mode
23        header: 'Middle Name',
24      },
25      {
26        accessorKey: 'lastName',
27        header: 'Last Name',
28        //if you do not want to use the default filter modes, you can provide your own and render your own menu
29        renderColumnFilterModeMenuItems: ({ onSelectFilterMode }) => [
30          <MenuItem key="0" onClick={() => onSelectFilterMode('contains')}>
31            <div>Contains</div>
32          </MenuItem>,
33          <MenuItem
34            key="1"
35            onClick={() => onSelectFilterMode('customFilterFn')}
36          >
37            <div>Custom Filter Fn</div>
38          </MenuItem>,
39        ],
40      },
41      {
42        accessorKey: 'age',
43        columnFilterModeOptions: ['between', 'greaterThan', 'lessThan'], //only allow these filter modes
44        filterFn: 'between',
45        header: 'Age',
46      },
47    ],
48    [],
49  );
50
51  return (
52    <MaterialReactTable
53      columns={columns}
54      data={data}
55      enableColumnFilterModes //enable changing filter mode for all columns unless explicitly disabled in a column def
56      initialState={{ showColumnFilters: true }} //show filters by default
57      filterFns={{
58        customFilterFn: (row, id, filterValue) => {
59          return row.getValue(id) === filterValue;
60        },
61      }}
62      localization={
63        {
64          filterCustomFilterFn: 'Custom Filter Fn',
65        } as any
66      }
67    />
68  );
69};
70
71export default Example;
72

Expanded Leaf Row Filtering Options

If you are using the filtering features along-side either the grouping or expanding features, then there are a few behaviors and customizations you should be aware of.

Check out the Expanded Leaf Row Filtering Behavior docs to learn more about the filterFromLeafRows and maxLeafRowFilterDepth props.

Manual Server-Side Column Filtering

A very common use case when you have a lot of data is to filter the data on the server, instead of client-side. In this case, you will want to set the manualFiltering prop to true and manage the columnFilters state yourself like so (can work in conjunction with manual global filtering).

// You can manage and have control over the columnFilters state yourself
const [columnFilters, setColumnFilters] = useState([]);
const [data, setData] = useState([]); //data will get updated after re-fetching

useEffect(() => {
  const fetchData = async () => {
    // send api requests when columnFilters state changes
    const filteredData = await fetch();
    setData([...filteredData]);
  };
}, [columnFilters]);

return (
  <MaterialReactTable
    columns={columns}
    data={data} // this will already be filtered on the server
    manualFiltering //turn off client-side filtering
    onColumnFiltersChange={setColumnFilters} //hoist internal columnFilters state to your state
    state={{ columnFilters }} //pass in your own managed columnFilters state
  />
);

Specifying manualFiltering turns off all client-side filtering and assumes that the data you pass to <MaterialReactTable /> is already filtered.

Here is the full Remote Data example featuring server-side filtering, pagination, and sorting.

Demo

Open Stackblitz Open Code Sandbox Open on GitHub

	First Name	Last Name	Address	State	Phone Number
No records to display

Source Code

1import React, { FC, useEffect, useMemo, useState } from 'react';
2import MaterialReactTable, { MRT_ColumnDef } from 'material-react-table';
3import type {
4  ColumnFiltersState,
5  PaginationState,
6  SortingState,
7} from '@tanstack/react-table';
8
9type UserApiResponse = {
10  data: Array<User>;
11  meta: {
12    totalRowCount: number;
13  };
14};
15
16type User = {
17  firstName: string;
18  lastName: string;
19  address: string;
20  state: string;
21  phoneNumber: string;
22};
23
24const Example: FC = () => {
25  //data and fetching state
26  const [data, setData] = useState<User[]>([]);
27  const [isError, setIsError] = useState(false);
28  const [isLoading, setIsLoading] = useState(false);
29  const [isRefetching, setIsRefetching] = useState(false);
30  const [rowCount, setRowCount] = useState(0);
31
32  //table state
33  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
34  const [globalFilter, setGlobalFilter] = useState('');
35  const [sorting, setSorting] = useState<SortingState>([]);
36  const [pagination, setPagination] = useState<PaginationState>({
37    pageIndex: 0,
38    pageSize: 10,
39  });
40
41  //if you want to avoid useEffect, look at the React Query example instead
42  useEffect(() => {
43    const fetchData = async () => {
44      if (!data.length) {
45        setIsLoading(true);
46      } else {
47        setIsRefetching(true);
48      }
49
50      const url = new URL(
51        '/api/data',
52        process.env.NODE_ENV === 'production'
53          ? 'https://www.material-react-table.com'
54          : 'http://localhost:3000',
55      );
56      url.searchParams.set(
57        'start',
58        `${pagination.pageIndex * pagination.pageSize}`,
59      );
60      url.searchParams.set('size', `${pagination.pageSize}`);
61      url.searchParams.set('filters', JSON.stringify(columnFilters ?? []));
62      url.searchParams.set('globalFilter', globalFilter ?? '');
63      url.searchParams.set('sorting', JSON.stringify(sorting ?? []));
64
65      try {
66        const response = await fetch(url.href);
67        const json = (await response.json()) as UserApiResponse;
68        setData(json.data);
69        setRowCount(json.meta.totalRowCount);
70      } catch (error) {
71        setIsError(true);
72        console.error(error);
73        return;
74      }
75      setIsError(false);
76      setIsLoading(false);
77      setIsRefetching(false);
78    };
79    fetchData();
80    // eslint-disable-next-line react-hooks/exhaustive-deps
81  }, [
82    columnFilters,
83    globalFilter,
84    pagination.pageIndex,
85    pagination.pageSize,
86    sorting,
87  ]);
88
89  const columns = useMemo<MRT_ColumnDef<User>[]>(
90    () => [
91      {
92        accessorKey: 'firstName',
93        header: 'First Name',
94      },
95      //column definitions...
96      {
97        accessorKey: 'lastName',
98        header: 'Last Name',
99      },
100      {
101        accessorKey: 'address',
102        header: 'Address',
103      },
104      {
105        accessorKey: 'state',
106        header: 'State',
107      },
108      {
109        accessorKey: 'phoneNumber',
110        header: 'Phone Number',
111      },
112      
113    ],
114    [],
115  );
116
117  return (
118    <MaterialReactTable
119      columns={columns}
120      data={data}
121      enableRowSelection
122      getRowId={(row) => row.phoneNumber}
123      initialState={{ showColumnFilters: true }}
124      manualFiltering
125      manualPagination
126      manualSorting
127      muiToolbarAlertBannerProps={
128        isError
129          ? {
130              color: 'error',
131              children: 'Error loading data',
132            }
133          : undefined
134      }
135      onColumnFiltersChange={setColumnFilters}
136      onGlobalFilterChange={setGlobalFilter}
137      onPaginationChange={setPagination}
138      onSortingChange={setSorting}
139      rowCount={rowCount}
140      state={{
141        columnFilters,
142        globalFilter,
143        isLoading,
144        pagination,
145        showAlertBanner: isError,
146        showProgressBars: isRefetching,
147        sorting,
148      }}
149    />
150  );
151};
152
153export default Example;
154

Customize MUI Filter components

You can customize the MUI filter components by setting the muiTableHeadCellFilterTextFieldProps prop or column option.

You can also turn a filter textfield into a select dropdown by setting the filterSelectOptions prop or column option.

Demo

Open Stackblitz Open Code Sandbox Open on GitHub

ID	First Name	Last Name	Gender Filter by Gender	Age
1	Hugh	Mungus	Male	42
2	Leroy	Jenkins	Male	51
3	Candice	Nutella	Female	27
4	Micah	Johnson	Other	32

Source Code

1import React, { FC, useMemo } from 'react';
2import MaterialReactTable, { MRT_ColumnDef } from 'material-react-table';
3
4export type Person = {
5  id: number;
6  firstName: string;
7  lastName: string;
8  gender: string;
9  age: number;
10};
11
12const Example: FC = () => {
13  const columns = useMemo<MRT_ColumnDef<Person>[]>(
14    () => [
15      {
16        accessorKey: 'id',
17        header: 'ID',
18        muiTableHeadCellFilterTextFieldProps: { placeholder: 'ID' },
19      },
20      {
21        accessorKey: 'firstName',
22        header: 'First Name',
23      },
24      {
25        accessorKey: 'lastName',
26        header: 'Last Name',
27      },
28      {
29        accessorKey: 'gender',
30        header: 'Gender',
31        filterFn: 'equals',
32        filterSelectOptions: [
33          { text: 'Male', value: 'Male' },
34          { text: 'Female', value: 'Female' },
35          { text: 'Other', value: 'Other' },
36        ],
37        filterVariant: 'select',
38      },
39      {
40        accessorKey: 'age',
41        header: 'Age',
42        filterVariant: 'range',
43      },
44    ],
45    [],
46  );
47
48  const data = useMemo<Person[]>(
49    //data definitions...
50    () => [
51      {
52        id: 1,
53        firstName: 'Hugh',
54        lastName: 'Mungus',
55        gender: 'Male',
56        age: 42,
57      },
58      {
59        id: 2,
60        firstName: 'Leroy',
61        lastName: 'Jenkins',
62        gender: 'Male',
63        age: 51,
64      },
65      {
66        id: 3,
67        firstName: 'Candice',
68        lastName: 'Nutella',
69        gender: 'Female',
70        age: 27,
71      },
72      {
73        id: 4,
74        firstName: 'Micah',
75        lastName: 'Johnson',
76        gender: 'Other',
77        age: 32,
78      },
79    ],
80    [],
81    
82  );
83
84  return (
85    <MaterialReactTable
86      columns={columns}
87      data={data}
88      initialState={{ showColumnFilters: true }} //show filters by default
89      muiTableHeadCellFilterTextFieldProps={{
90        sx: { m: '0.5rem 0', width: '100%' },
91        variant: 'outlined',
92      }}
93    />
94  );
95};
96
97export default Example;
98

Custom Filter Components

If you need custom filter components that are much more complex than text-boxes and dropdowns, you can create and pass in your own filter components using the Filter column option.

View Extra Storybook Examples

Relevant Props

Relevant Column Options

Relevant State Options

Disable Filtering Features

Demo

Source Code

Filter Variants

Demo

Source Code

Custom Filter Functions

Custom Filter Functions Per Column

Pre-built MRT Filter Functions

Pre-built TanStack Table Filter Functions

Add Custom Filter Functions

Filter Modes

Enable Column Filter Modes (Filter Switching)

Customize Filter Modes

Render Custom Filter Mode Menu

Demo

Source Code

Expanded Leaf Row Filtering Options

Manual Server-Side Column Filtering

Demo

Source Code

Customize MUI Filter components

Demo

Source Code

Custom Filter Components