Core Features

Advanced Features

React Data GridAdvanced Filter - Custom Filter Options

Version 36.2.0
Enterprise

Custom Filter Options defined for a column are also offered in the Advanced Filter, so an expression can use the same options as the column filter.

Configuring Custom Filter Options Copy Link

The Advanced Filter accepts Custom Filter Options the same way as Column Filters. Each Custom Filter Option is an IFilterOptionDef with the following properties.

displayKeyCopy Link
string
A unique key that does not clash with the built-in filter keys.
displayNameCopy Link
string
Display name for the filter. Can be replaced by a locale-specific value using a localeTextFunc.
predicateCopy Link
Function
Custom filter logic returning a boolean from the filterValues and cellValue; params names the column and the calling filter.
numberOfInputsCopy Link
0 | 1 | 2
Number of inputs for this option, and the values an Advanced Filter writes. Defaults to 1, clamped to 0-2.

Options taking two values are validated like is between: the first value must be less than the second, or equal to it where inRangeInclusive = true.

The predicate only runs with the Client-Side Row Model. With the Server-Side Row Model the option is sent to the server as its displayKey in the filter model, as for the Set Filter options.

The following example demonstrates custom filter options taking different numbers of values:

  • The Athlete column has Starts With A (no values) and Does Not Start With (one value).
  • The Age column has Even Numbers (no values) and Between (Exclusive) (two values).
  • The Date column has Leap Year (no values) and Between (Exclusive) (two dates).
const [columnDefs, setColumnDefs] = useState([
    {
        field: 'age',
        filterParams: {
            filterOptions: [
                'equals',
                {
                    displayKey: 'evenNumbers',
                    displayName: 'Even Numbers',
                    numberOfInputs: 0,
                    predicate: (_values, cellValue) => cellValue != null && cellValue % 2 === 0,
                },
                {
                    displayKey: 'betweenExclusive',
                    displayName: 'Between (Exclusive)',
                    numberOfInputs: 2,
                    predicate: ([from, to], cellValue) => cellValue != null && cellValue > from && cellValue < to,
                },
            ],
        },
    },
]);

<AgGridReact columnDefs={columnDefs} />

Using Custom Filter Options in the Advanced Filter Input Copy Link

Custom Filter Options are typed into the Advanced Filter input using their displayName, followed by its values. Using the options from the example above these are some example inputs:

[Athlete] Starts With A
[Athlete] Does Not Start With "Michael"
[Age] Even Numbers
[Age] Between (Exclusive) (30, 40)
[Date] Between (Exclusive) ("2008-08-20", "2008-08-25")

Values are quoted according to the column's Cell Data Type, as for the built-in options: numbers are unquoted, everything else is quoted. Two values are separated by a comma; the surrounding brackets are optional. Where the displayKey has a localised entry, that text is used as the option name instead.

A displayKey is resolved against the column being filtered, so different columns can reuse the same key. Reusing an Option Key from the table of standard options, for example contains, replaces that built-in option for the column, the same as it does in the column filter.

Filter Model Copy Link

A condition using a Custom Filter Option stores the displayKey in type, and the values in filter and filterTo. See Filter Model / API for saving and restoring the Advanced Filter state.

const advancedFilterModel = {
    filterType: 'number',
    colId: 'age',
    type: 'betweenExclusive',
    filter: 30,
    filterTo: 40,
};