JavaScript Data Grid: Column Filter

Column filters are filters that are applied to the data at the column level. Many column filters can be active at once (e.g. filters set on different columns) and the grid will display rows that pass every column's filter.

Column filters are accessed in the grid UI either through the Column Menu or the Tool Panel.

Access via Column Menu

Access via Tool Panel

You can use the Provided Filters that come with the grid, or you can build your own Filter Components if you want to customise the filter experience to your application.

Example: Simple Filters

The example below demonstrates simple filters. The following can be noted:

• Column Athlete has a simple text filter.
• Column Age has a simple number filter.
• Column Date has a simple date filter.

// Loading...

Configuring Filters on Columns

Set filtering on a column using the column definition property filter. The property can have one of the following values:

• boolean: Set to true to enable the default filter. The default is Text Filter for AG Grid Community and Set Filter for AG Grid Enterprise.
• string / Component: Provide a specific filter to use instead of the default filter.

The code below shows some column definitions with filters set:

const gridOptions = {
    columnDefs: [
        // sets the text filter
        { field: 'athlete', filter: 'agTextColumnFilter' },

        // sets the number filter
        { field: 'age', filter: 'agNumberColumnFilter' },

        // use the default filter
        { field: 'gold', filter: true },

        // use no filter (leaving unspecified means use no filter)
        { field: 'sport' },
    ],

    // other grid options ...
}

If you want to enable filters on all columns, you should set a filter on the Default Column Definition. The following code snippet shows setting filter=true for all columns via the defaultColDef and then setting filter=false for the Sport column, so all columns have a filter except Sport.

const gridOptions = {
    // anything specified in defaultColDef gets applied to all columns
    defaultColDef: {
        // set filtering on for all columns
        filter: true,
    },

    columnDefs: [
        // filter not specified, defaultColDef setting is used
        { field: 'athlete' },
        { field: 'age' },

        // filter specifically set to 'false', i.e. use no filter
        { field: 'sport', filter: false },
    ],

    // other grid options ...
}

Filter Parameters

Each filter can take additional filter parameters by setting colDef.filterParams. The parameters each filter type accepts are specific to each filter; parameters for the provided filters are explained in their relevant sections.

The code below shows configuring the text filter on the Athlete column and providing extra filter parameters (what the buttons do is explained in Apply, Clear, Reset and Cancel Buttons).

const gridOptions = {
    columnDefs: [
        // column configured to use text filter
        {
            field: 'athlete',
            filter: 'agTextColumnFilter',
            // pass in additional parameters to the text filter
            filterParams: {
                buttons: ['reset', 'apply'],
                debounceMs: 200
            }
        }
    ],

    // other grid options ...
}

Filter Values

By default, the values supplied to the filter are retrieved from the data based on the field attribute. This can be overridden by providing a filterValueGetter in the Column Definition as shown below. This is similar to using a Value Getter, but is specific to the filter. This parameter is required when filtering on row group columns.

filterValueGetter: string | ValueGetterFunc<TData>;

interface ValueGetterFunc<TData = any> {
    (params: ValueGetterParams<TData>) : any
}

interface ValueGetterParams<TData = any> {
  // A utility method for getting other column values 
  getValue: (field: string) => any;
  // Row node for the given row 
  node: IRowNode<TData> | null;
  // Data associated with the node 
  data: TData | undefined;
  // Column for this callback 
  column: Column;
  // ColDef provided for this column 
  colDef: ColDef<TData>;
  // The grid api. 
  api: GridApi<TData>;
  // The column api. 
  columnApi: ColumnApi;
  // Application context as set on `gridOptions.context`. 
  context: any;
}

const gridOptions = {
    columnDefs: [
        { field: 'country', rowGroup: true, hide: true },
        { field: 'year', rowGroup: true, hide: true },
        { field: 'gold' },
    ],
    autoGroupColumnDef: { 
        // enables filtering on the group column
        filter: true,
        // supplies 'country' values to the filter 
        filterValueGetter: params => params.data.country,                          
    },
    groupDisplayType: 'singleColumn',

    // other grid options ...
}

Filter Events

Filtering causes the following events to be emitted:

onFilterOpened = (
    event: FilterOpenedEvent<TData>
) => void;

interface FilterOpenedEvent<TData = any> {
  // Column / OriginalColumnGroup that contains the filter 
  column: Column | ProvidedColumnGroup;
  // Source of the open request 
  source: FilterRequestSource;
  // Parent element of the filter 
  eGui: HTMLElement;
  // The grid api. 
  api: GridApi<TData>;
  // The column api. 
  columnApi: ColumnApi;
  // Application context as set on `gridOptions.context`. 
  context: any;
  // Event identifier 
  type: string;
}

type FilterRequestSource = 
      'COLUMN_MENU' 
    | 'TOOLBAR' 
    | 'NO_UI'

onFilterChanged = (
    event: FilterChangedEvent<TData>
) => void;

interface FilterChangedEvent<TData = any> {
  // True if the filter was changed as a result of data changing 
  afterDataChange?: boolean;
  // True if filter was changed via floating filter 
  afterFloatingFilter?: boolean;
  // Columns affected by the filter change. Array contents depend on the source of the event.
  //
  // - Expect 1 element for UI-driven column filter changes.
  // - Expect 0-N elements (all affected columns) for calls to `gridOptions.api.setFilterModel()`.
  // - Expect 0-N elements (removed columns) for calls to `gridOptions.api.setColumnDefs()`.
  // - Expect 0 elements for quick-filters and calls to `gridOptions.api.onFilterChanged()`.
  columns: Column[];
  // The grid api. 
  api: GridApi<TData>;
  // The column api. 
  columnApi: ColumnApi;
  // Application context as set on `gridOptions.context`. 
  context: any;
  // Event identifier 
  type: string;
}

onFilterModified = (
    event: FilterModifiedEvent<TData>
) => void;

interface FilterModifiedEvent<TData = any> {
  filterInstance: IFilterComp;
  column: Column;
  // The grid api. 
  api: GridApi<TData>;
  // The column api. 
  columnApi: ColumnApi;
  // Application context as set on `gridOptions.context`. 
  context: any;
  // Event identifier 
  type: string;
}

Filtering Animation

To enable animation of the rows when filtering, set the grid property animateRows=true.

Relation to Quick Filter and External Filter

Column filters work independently of Quick Filter and External Filter. If a quick filter and / or external filter are applied along with a column filter, each filter type is considered and the row will only show if it passes all three types.

Column filters are tied to a specific column. Quick filter and external filter are not tied to any particular column. This section of the documentation talks about column filters only. For quick filter and external filter, click the links above to learn more.

Provided Filters

There are four filters that are provided by the grid. These are as follows:

See the Provided Filters section for more details on using them.