The ability for a column to be column filtered is determined by the following:
createDataColumn
or a valid accessorKey
/accessorFn
.column.enableColumnFilter
is not set to false
options.enableColumnFilters
is not set to false
options.enableFilters
is not set to false
The ability for a column to be globally filtered is determined by the following:
createDataColumn
or a valid accessorKey
/accessorFn
.options.getColumnCanGlobalFilter
returns true
for the given column. If it is not provided, the column is assumed to be globally filterable.column.enableColumnFilter
is not set to false
options.enableColumnFilters
is not set to false
options.enableFilters
is not set to false
Filter state is stored on the table instance using the following shape:
export type FiltersTableState = { columnFilters: ColumnFiltersState globalFilter: any}
export type ColumnFiltersState = ColumnFilter[]
export type ColumnFilter = { id: string value: unknown}
The following filter functions are built-in to the table core:
includesString
includesStringSensitive
equalsString
equalsStringSensitive
arrIncludes
arrIncludesAll
arrIncludesSome
equals
Object.is
/===
weakEquals
==
inNumberRange
Every filter function receives:
and should return true
if the row should be included in the filtered rows, and false
if it should be removed.
This is the type signature for every filter function:
export type FilterFn<TGenerics extends TableGenerics> = { ( row: Row<TGenerics>, columnId: string, filterValue: any, addMeta: (meta: TGenerics['FilterMeta']) => void ): boolean resolveFilterValue?: TransformFilterValueFn<TGenerics> autoRemove?: ColumnFilterAutoRemoveTestFn<TGenerics> addMeta?: (meta?: TGenerics['FilterMeta']) => void}
export type TransformFilterValueFn<TGenerics extends TableGenerics> = ( value: any, column?: Column<TGenerics>) => unknown
export type ColumnFilterAutoRemoveTestFn<TGenerics extends TableGenerics> = ( value: any, column?: Column<TGenerics>) => boolean
export type CustomFilterFns<TGenerics extends TableGenerics> = Record< string, FilterFn<TGenerics>>
filterFn.resolveFilterValue
This optional "hanging" method on any given filterFn
allows the filter function to transform/sanitize/format the filter value before it is passed to the filter function.
filterFn.autoRemove
This optional "hanging" method on any given filterFn
is passed a filter value and expected to return true
if the filter value should be removed from the filter state. eg. Some boolean-style filters may want to remove the filter value from the table state if the filter value is set to false
.
Filter functions can be used/referenced/defined by passing the following to columnDefinition.filterFn
or options.globalFilterFn
:
string
that references a built-in filter functionstring
that references a custom filter functions provided via the tableOptions.filterFns
optioncolumnDefinition.filterFn
optionThe final list of filter functions available for the columnDef.filterFn
and ``tableOptions.globalFilterFn` options use the following type:
export type FilterFnOption<TGenerics extends TableGenerics> = | 'auto' | BuiltInFilterFn | keyof TGenerics['FilterFns'] | FilterFn<TGenerics>
Filtering data can often expose additional information about the data that can be used to aid other future operations on the same data. A good exmaple of this concept is a ranking-system like that of match-sorter
that simutaneously ranks, filters and sorts data. While utilities like match-sorter
make a lot of sense for single-dimensional filter+sort tasks, the decoupled filtering/sorting architecture of building a table makes them very difficult and unperformant to use.
To make a ranking/filtering/sorting system work with tables, filterFn
s can optionally mark results with a filter meta value that can be used later to sort/group/etc the data to your liking. This is done by calling the addMeta
function supplied to your custom filterFn
.
Below is an example using our own match-sorter-utils
package (a utility fork of match-sorter
) to rank, filter, and sort the data
import { Column, createTable, TableInstance, useTableInstance, ColumnFiltersState, getCoreRowModel, getFilteredRowModel, getFacetedRowModel, getFacetedUniqueValues, getFacetedMinMaxValues, getPaginationRowModel, sortingFns,} from '@tanstack/react-table'
import { RankingInfo, rankItem, compareItems,} from '@tanstack/match-sorter-utils'
let table = createTable() .setFilterMetaType<RankingInfo>() .setOptions({ filterFns: { fuzzy: (row, columnId, value, addMeta) => { // Rank the item const itemRank = rankItem(row.getValue(columnId), value)
// Store the ranking info addMeta(itemRank)
// Return if the item should be filtered in/out return itemRank.passed }, }, sortingFns: { fuzzy: (rowA, rowB, columnId) => { let dir = 0
// Only sort by rank if the column has ranking information if (rowA.columnFiltersMeta[columnId]) { dir = compareItems( rowA.columnFiltersMeta[columnId]!, rowB.columnFiltersMeta[columnId]! ) }
// Provide an alphanumeric fallback for when the item ranks are equal return dir === 0 ? sortingFns.alphanumeric(rowA, rowB, columnId) : dir }, }, })
filterFn
filterFn?: FilterFn | keyof TGenerics['FilterFns'] | keyof BuiltInFilterFns
The filter function to use with this column.
Options:
string
referencing a built-in filter function)string
referencing a custom filter function defined on the filterFns
table optionenableColumnFilter
enableColumnFilter?: boolean
Enables/disables the column filter for this column. For option priority, see Can-Filter Option Priority.
enableGlobalFilter
enableGlobalFilter?: boolean
Enables/disables the global filter for this column. For option priority, see Can-Filter Option Priority.
getCanFilter
getCanFilter: () => boolean
Returns whether or not the column can be column filtered.
getCanGlobalFilter
getCanGlobalFilter: () => boolean
Returns whether or not the column can be globally filtered.
getFilterIndex
getFilterIndex: () => number
Returns the index (including -1
) of the column filter in the table's state.columnFilters
array.
getIsFiltered
getIsFiltered: () => boolean
Returns whether or not the column is currently filtered.
getFilterValue
getFilterValue: () => unknown
Returns the current filter value of the column.
setFilterValue
setFilterValue: (updater: Updater<any>) => void
A function that sets the current filter value for the column. You can pass it a value or an updater function for immutability-safe operations on existing values.
getAutoFilterFn
getAutoFilterFn: (columnId: string) => FilterFn<TGenerics> | undefined
Returns an automatically calculated filter function for the column based off of the columns first known value.
getFilterFn
getFilterFn: (columnId: string) => FilterFn<TGenerics> | undefined
Returns the filter function (either user-defined or automatic, depending on configuration) for the columnId specified.
getFacetedRowModel
type getFacetedRowModel = () => RowModel<TGenerics>
⚠️ Requires that you pass a valid
getFacetedRowModel
function tooptions.facetedRowModel
. A default implementation is provided via the exportedgetFacetedRowModel
function.
Returns the row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts.
getFacetedUniqueValues
getFacetedUniqueValues: () => Map<any, number>
⚠️ Requires that you pass a valid
getFacetedUniqueValues
function tooptions.getFacetedUniqueValues
. A default implementation is provided via the exportedgetFacetedUniqueValues
function.
A function that computes and returns a Map
of unique values and their occurences derived from column.getFacetedRowModel
. Useful for displaying faceted result values.
getFacetedMinMaxValues
getFacetedMinMaxValues: () => Map<any, number>
⚠️ Requires that you pass a valid
getFacetedMinMaxValues
function tooptions.getFacetedMinMaxValues
. A default implementation is provided via the exportedgetFacetedMinMaxValues
function.
A function that computes and returns a min/max tuple derived from column.getFacetedRowModel
. Useful for displaying faceted result values.
columnFilters
columnFilters: Record<string, boolean>
The column filters map for the row. This object tracks whether a row is passing/failing specific filters by their column ID.
columnFiltersMeta
columnFiltersMeta: Record<string, TGenerics['FilterMeta']>
The column filters meta map for the row. This object tracks any filter meta for a row as optionally provided during the filtering process.
filterFromLeafRows
filterFromLeafRows?: boolean
By default, filtering is done from parent rows down (so if a parent row is filtered out, all of its children will be filtered out as well). Setting this option to true
will cause filtering to be done from leaf rows up (which means parent rows will be included so long as one of their child or grand-child rows is also included).
filterFns
filterFns?: Record<string, FilterFn>
Normally set ahead of time when using the createTable()
helper, this option allows you to define custom filter functions that can be referenced by their string key.
Example:
const table = createTable().setOptions({ filterFns: { myCustomFilterFn: (rows, columnIds, filterValue) => { // return the filtered rows }, },})
const column = table.createDataColumn('key', { filterFn: 'myCustomFilterFn',})
enableFilters
enableFilters?: boolean
Enables/disables all filters for the table. For option priority, see Can-Filter Option Priority.
manualFiltering
manualFiltering?: boolean
Disables the getFilteredRowModel
from being used to filter data. This may be useful if your table needs to dynamically support both client-side and server-side filtering.
onColumnFiltersChange
onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>
If provided, this function will be called with an updaterFn
when state.columnFilters
changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table.
enableColumnFilters
enableColumnFilters?: boolean
Enables/disables all column filters for the table. For option priority, see Can-Filter Option Priority.
getFilteredRowModel
getFilteredRowModel?: ( instance: TableInstance<TGenerics>) => () => RowModel<TGenerics>
If provided, this function is called once per table instance and should return a new function which will calculate and return the row model for the table when it's filtered.
{ getFilteredRowModel }
export.Example:
import { getFilteredRowModel } from '@tanstack/[adapter]-table'
useTableInstance(table, { getFilteredRowModel: getFilteredRowModel(),})
getColumnFacetedRowModel
getColumnFacetedRowModel: (columnId: string) => RowModel<TGenerics>
Returns the faceted row model for a given columnId.
globalFilterFn
globalFilterFn?: FilterFn | keyof TGenerics['FilterFns'] | keyof BuiltInFilterFns
The filter function to use for global filtering.
Options:
string
referencing a built-in filter function)string
referencing a custom filter function defined on the filterFns
table optiononGlobalFilterChange
onGlobalFilterChange?: OnChangeFn<GlobalFilterState>
If provided, this function will be called with an updaterFn
when state.globalFilter
changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table.
enableGlobalFilter
enableGlobalFilter?: boolean
Enables/disables the global filter for the table. For option priority, see Can-Filter Option Priority.
getColumnCanGlobalFilter
getColumnCanGlobalFilter?: (column: Column<TGenerics>) => boolean
If provided, this function will be called with the column and should return true
or false
to indicate whether this column should be used for global filtering.
setColumnFilters
setColumnFilters: (updater: Updater<ColumnFiltersState>) => void
Sets or updates the state.columnFilters
state.
resetColumnFilters
resetColumnFilters: (defaultState?: boolean) => void
Resets the columnFilters state to initialState.columnFilters
, or true
can be passed to force a default blank state reset to []
.
getPreFilteredRowModel
getPreFilteredRowModel: () => RowModel<TGenerics>
Returns the row model for the table before any column filtering has been applied.
getFilteredRowModel
getFilteredRowModel: () => RowModel<TGenerics>
Returns the row model for the table after column filtering has been applied.
setGlobalFilter
setGlobalFilter: (updater: Updater<any>) => void
Sets or updates the state.globalFilter
state.
resetGlobalFilter
resetGlobalFilter: (defaultState?: boolean) => void
Resets the globalFilter state to initialState.globalFilter
, or true
can be passed to force a default blank state reset to undefined
.
getGlobalAutoFilterFn
getGlobalAutoFilterFn: (columnId: string) => FilterFn<TGenerics> | undefined
Currently, this function returns the built-in includesString
filter function. In future releases, it may return more dynamic filter functions based on the nature of the data provided.
getGlobalFilterFn
getGlobalFilterFn: (columnId: string) => FilterFn<TGenerics> | undefined
Returns the global filter function (either user-defined or automatic, depending on configuration) for the table.
getGlobalFacetedRowModel
getGlobalFacetedRowModel: () => RowModel<TGenerics>
Returns the faceted row model for the global filter.
getGlobalFacetedUniqueValues
getGlobalFacetedUniqueValues: () => Map<any, number>
Returns the faceted unique values for the global filter.
getGlobalFacetedMinMaxValues
getGlobalFacetedMinMaxValues: () => [number, number]
Returns the faceted min and max values for the global filter.