Framework:Javascript GridAngular GridReact GridVue Grid

React Grid: Simple Filters

The grid provides three Simple Filters for filtering strings, numbers and dates.

Text Filter
Text Filter
Number Filter
Number Filter
Date Filter
Date Filter

Each of the filters works in a similar way. This page describes the common parts of the Simple Filters.

Example: Simple Filters

The example below demonstrates all three Simple Filters working. Note the following:

  • The Athlete column has a Text Filter.
  • The Age column has a Number Filter.
  • The Date column has a Date Filter.
  • filter=false is set on the Total column to disable the filter.

Remember Filtering works with all frameworks (e.g. Angular and React) as well as plain JavaScript.

Simple Filter Parts

Each Simple Filter follows the same layout. The only layout difference is the type of input field presented to the user: for Text and Number Filters a text field is displayed, whereas for Date Filters a date picker field is displayed.

Filter Panel Component

Filter Options

Each filter provides a dropdown list of filter options to select from. Each filter option represents a filtering strategy, e.g. 'equals', 'not equals', etc.

Each filter's default Filter Options are listed below, as well as information on Defining Custom Filter Options.

Filter Value

Each filter option takes zero (a possibility with custom options), one (for most) or two (for 'in range') values. The value type depends on the filter type, e.g. the Date Filter takes Date values.

Condition 1 and Condition 2

Each filter initially only displays Condition 1. When the user completes the Condition 1 section of the filter, Condition 2 becomes visible.

Join Operator

The Join Operator decides how Condition 1 and Condition 2 are joined, using either AND or OR.

Simple Filters Parameters

Simple Filters are configured though the filterParams attribute of the column definition. All of the parameters from Provided Filters are available:

buttons
string[]
Specifies the buttons to be shown in the filter, in the order they should be displayed in. The options are:
  • 'apply': If the Apply button is present, the filter is only applied after the user hits the Apply button.
  • 'clear': The Clear button will clear the (form) details of the filter without removing any active filters on the column.
  • 'reset': The Reset button will clear the details of the filter and any active filters on that column.
  • 'cancel': The Cancel button will discard any changes that have been made to the filter in the UI, restoring the applied model.
closeOnApply
boolean
If the Apply button is present, the filter popup will be closed immediately when the Apply or Reset button is clicked if this is set to true.
Default: false
debounceMs
number
By default the Text and Number filters will debounce by 500ms. This is because these filters have text field inputs, so time is given to the user to type items in before the input is formatted and the filtering applied. The Set and Date will execute immediately (no debounce). To override these defaults, set debounceMs to the number of milliseconds to debounce by.
newRowsAction
string
This property is for when using the Client Side Row Model only. When set to 'clear', updating the data in the grid by calling api.setRowData() (or updating the rowData property if bound by a framework) will clear (reset) the filter. If you instead set this to 'keep', the grid will keep its currently set filter when the data is updated.
Default: 'clear'
Options: 'clear', 'keep'

In addition, the following parameters are also available, depending on the type of filter being used:

alwaysShowBothConditions
boolean
By default, only one condition is shown, and a second is made visible once a first condition has been entered. Set this to true to always show both conditions. In this case the second condition will be disabled until a first condition has been entered.
Default: false
Text, Number, Date
filterOptions
string[]
Array of Filter Options to present to the user.
Options: 'equals', 'notEqual', 'contains', 'notContains', 'startsWith', 'endsWith', 'lessThan', 'lessThanOrEqual', 'greaterThan', 'greaterThanOrEqual', 'inRange', 'empty'
Text, Number, Date
defaultOption
string
The default Filter Option to be selected.
Options: 'equals', 'notEqual', 'contains', 'notContains', 'startsWith', 'endsWith', 'lessThan', 'lessThanOrEqual', 'greaterThan', 'greaterThanOrEqual', 'inRange', 'empty'
Text, Number, Date
defaultJoinOperator
string
By default, the two conditions are combined using AND. You can change this default by setting this property.
Options: 'AND', 'OR'
Text, Number, Date
suppressAndOrCondition
boolean
If true, the filter will only allow one condition.
Default: false
Text, Number, Date
textCustomComparator
Used to override how to filter based on the user input. See Text Custom Comparator.
Text
caseSensitive
boolean
By default, text filtering is case-insensitive. Set this to true to make text filtering case-sensitive.
Default: false
Text
textFormatter
Formats the text before applying the filter compare logic. Useful if you want to substitute accented characters, for example.
Text
trimInput
boolean
If true, the input that the user enters will be trimmed when the filter is applied, so any leading or trailing whitespace will be removed. If only whitespace is entered, it will be left as-is. If you enable trimInput, it is best to also increase the debounceMs to give users more time to enter text.
Default: false
Text
inRangeInclusive
If true, the 'inRange' filter option will include values equal to the start and end of the range.
Number, Date
includeBlanksInEquals
If true, blank (null or undefined) values will pass the 'equals' filter option.
Number, Date
includeBlanksInLessThan
If true, blank (null or undefined) values will pass the 'lessThan' and 'lessThanOrEqual' filter options.
Number, Date
includeBlanksInGreaterThan
If true, blank (null or undefined) values will pass the 'greaterThan' and 'greaterThanOrEqual' filter options.
Number, Date
includeBlanksInRange
If true, blank (null or undefined) values will pass the 'inRange' filter option.
Number, Date
allowedCharPattern
When specified, the input field will be of type text instead of number, and this will be used as a regex of all the characters that are allowed to be typed. This will be compared against any typed character and prevent the character from appearing in the input if it does not match, in supported browsers (all except Safari).
Number
numberParser
Typically used alongside allowedCharPattern, this provides a custom parser to convert the value entered in the filter inputs into a number that can be used for comparisons.
Number
comparator
Required if the data for the column are not native JS Date objects.
Date
browserDatePicker
This is only used if a date component is not provided. By default the grid will use the browser date picker in Chrome and Firefox and a plain text box for all other browsers (this is because Chrome and Firefox are the only current browsers providing a decent out-of-the-box date picker). If this property is set to true, the browser date picker will be used regardless of the browser type. If set to false, a plain text box will be used for all browsers.
Date
minValidYear
number
This is the minimum year that must be entered in a date field for the value to be considered valid.
Default: 1000
Date

Example: Simple Filter Options

The following example demonstrates those configuration options that can be applied to any Simple Filter.

  • The Athlete column shows a Text Filter with default behavior for all options.
  • The Country column shows a Text Filter with filterOptions set to show a different list of available options, and defaultOption set to change the default option selected.
  • The Age column has a Number Filter with alwaysShowBothConditions set to true so that both condition are always shown. The defaultJoinOperator is also set to 'OR' rather than the default ('AND').
  • The Date column has a Date Filter with suppressAndOrCondition set to true, so that only the first condition is shown.

Simple Filter Options

Each simple filter presents a list of options to the user. The list of options for each filter are as follows:

Option NameOption KeySupported Filters
EqualsequalsText, Number, Date
Not EqualsnotEqualText, Number, Date
ContainscontainsText
Not ContainsnotContainsText
Starts WithstartsWithText
Ends WithendsWithText
Less ThanlessThanNumber, Date
Less Than or EquallessThanOrEqualNumber
Greater ThangreaterThanNumber, Date
Greater Than or EqualgreaterThanOrEqualNumber
In RangeinRangeNumber, Date
Choose OneemptyText, Number, Date

Note that the empty filter option is primarily used when creating Custom Filter Options. When 'Choose One' is displayed, the filter is not active.

Default Filter Options

Each of the three filter types has the following default options and default selected option.

FilterDefault List of OptionsDefault Selected Option
TextContains, Not Contains, Equals, Not Equals, Starts With, Ends With.Contains
NumberEquals, Not Equals, Less Than, Less Than or Equal, Greater Than, Greater Than or Equal, In Range.Equals
DateEquals, Greater Than, Less Than, Not Equals, In Range.Equals

Simple Filter Models

When saving or restoring state on a filter, the Filter Model is used. The Filter Model represents the state of the filter. For example, the code below first gets and then sets the Filter Model for the Athlete column:

// get filter instance
const filterInstance = gridApi.getFilterInstance('athlete'); 

// get filter model
const model = filterInstance.getModel(); 

// set filter model and update
filterInstance.setModel({
    type: 'endsWith',
    filter: 'thing'
});

// refresh rows based on the filter (not automatic to allow for batching multiple filters)
gridApi.onFilterChanged();

This section explains what the Filter Model looks like for each of the simple filters. The interface used by each filter type is as follows:

The best way to understand what the Filter Models look like is to set a filter via the UI and call api.getFilterModel() in your console. You can then see what the model looks like for different variations of the filters.

// text filter uses this filter model
interface TextFilterModel {
    // always 'text' for text filter
    filterType: string;

    // one of the filter options, e.g. 'equals'
    type: string;

    // the text value associated with the filter.
    // it's optional as custom filters may not
    // have a text value
    filter?: string;
}
// number filter uses this filter model
interface NumberFilterModel {
    // always 'number' for number filter
    filterType: string;

    // one of the filter options, e.g. 'equals'
    type: string;

    // the number value(s) associated with the filter.
    // custom filters can have no values (hence both are optional).
    // range filter has two values (from and to).
    filter?: number;
    filterTo?: number;
}
// date filter uses this filter model
interface DateFilterModel {
    // always 'date' for date filter
    filterType: string;

    // one of the filter options, e.g. 'equals'
    type: string;

    // the date value(s) associated with the filter.
    // the type is string and format is always YYYY-MM-DD e.g. 2019-05-24
    // custom filters can have no values (hence both are optional).
    // range filter has two values (from and to).
    dateFrom?: string;
    dateTo?: string;
}

Examples of filter model instances are as follows:

// number filter with one condition, with equals type
const numberLessThan35 = {
    filterType: 'number',
    type: 'lessThan',
    filter: 35
};
// number filter with one condition, with inRange type
const numberBetween35And40 = {
    filterType: 'number',
    type: 'inRange',
    filter: 35,
    filterTo: 40
};

The filterType is not used by the grid when you call setFilterModel(). It is provided for information purposes only when you get the filter model. This is useful if you are doing server-side filtering, where the filter type may be used in building back-end queries.

If the filter has both Condition 1 and Condition 2 set, then two instances of the model are created and wrapped inside a Combined Model. A combined model looks as follows:

// A filter combining two conditions
// M is either TextFilterModel, NumberFilterModel or DateFilterModel
interface ICombinedSimpleModel<M> {
    // the filter type: date, number or text
    filterType: string;

    operator: JoinOperator;

    // two instances of the filter model
    condition1: M;
    condition2: M;
}

type JoinOperator = 'AND' | 'OR';

An example of a filter model with two conditions is as follows:

// number filter with two conditions, both are equals type
const numberEquals18OrEquals20 = {
    filterType: 'number',
    operator: 'OR',
    condition1: {
        filterType: 'number',
        type: 'equals',
        filter: 18
    },
    condition2: {
        filterType: 'number',
        type: 'equals',
        filter: 18
    }
};

Custom Filter Options

For applications that have bespoke filtering requirements, it is also possible to add new custom filtering options to the number, text and date filters. For example, a 'Not Equal (with Nulls)' filter option could be included alongside the built in 'Not Equal' option.

Custom filter options are supplied to the grid via filterParams.filterOptions and must conform to the following interface:

interface IFilterOptionDef {
    displayKey: string;
    displayName: string;
    test: (filterValue: any, cellValue: any) => boolean;
    hideFilterInput?: boolean;
}

The displayKey should contain a unique key value that doesn't clash with the built-in filter keys. A default displayName should also be provided but can be replaced by a locale-specific value using a localeTextFunc.

The custom filter logic is implemented through the test function, which receives the filterValue typed by the user along with the cellValue from the grid, and returns true or false.

It is also possible to hide the filter input field by enabling the optional property hideFilterInput.

Custom FilterOptionDefs can be supplied alongside the built-in filter option string keys as shown below:

const ageFilterParams = {
    filterOptions: [
        'lessThan',
        {
            displayKey: 'lessThanWithNulls',
            displayName: 'Less Than with Nulls',
            test: (filterValue, cellValue) => cellValue == null || cellValue < filterValue,
        },
        'greaterThan',
        {
            displayKey: 'greaterThanWithNulls',
            displayName: 'Greater Than with Nulls',
            test: (filterValue, cellValue) => cellValue == null || cellValue > filterValue,
        }
    ]
};

<AgGridReact>
    <AgGridColumn field="age" filter="agNumberColumnFilter" filterParams={ageFilterParams} />
</AgGridReact>

The following example demonstrates several custom filter options:

  • The Athlete column contains two custom filter options: Starts with "A" and Starts with "N". Both these options take no text filter input.
  • The Age column contains three custom filter options: evenNumbers, oddNumbers and blanks. It also uses the built-in 'empty' filter along with suppressAndOrCondition=true.
  • The Date column includes a custom equalsWithNulls filter. Note that a custom comparator is still required for the built-in date filter options, i.e. equals.
  • The Country column includes a custom notEqualNoNulls filter which also removes null values.
  • The Country columns also demonstrates how localisation can be achieved via the gridOptions.localeTextFunc() callback function, where the default value is replaced for the filter option 'notEqualNoNulls'.
  • Saving and restoring custom filter options via api.getFilterModel() and api.setFilterModel() can be tested using the provided buttons.

Blank Cells (Date and Number Filters)

If the row data contains blanks (i.e. null or undefined), by default the row won't be included in filter results. To change this, use the filter params includeBlanksInEquals, includeBlanksInLessThan, includeBlanksInGreaterThan and includeBlanksInRange. For example, the code snippet below configures a filter to include null for equals, but not for less than, greater than or in range:

const filterParams = {
    includeBlanksInEquals: true,
    includeBlanksInLessThan: false,
    includeBlanksInGreaterThan: false,
    includeBlanksInRange: false,
};

In the following example you can filter by age or date and see how blank values are included. Note the following:

  • Columns Age and Date have both null and undefined values resulting in blank cells.
  • Toggle the controls on the top to see how includeBlanksInEquals, includeBlanksInLessThan, includeBlanksInGreaterThan and includeBlanksInRange impact the search result.

Style Header on Filter

Each time a filter is applied to a column the CSS class ag-header-cell-filtered is added to the header. This can be used for adding style to headers that are filtered.

In the example below, we've added some styling to ag-header-cell-filtered, so when you filter a column you will notice the column header change.