Column Filters

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.

Provided Filters

Basic Filter

The example below demonstrates simple filters. Note that the “Age” column has a number filter, the
date has a date filter and the other columns have a text filter.

import dash_ag_grid as dag
from dash import Dash, html, dcc
import pandas as pd

app = Dash(__name__)


df = pd.read_csv(
    "https://raw.githubusercontent.com/plotly/datasets/master/ag-grid/olympic-winners.csv"
)

# basic columns definition with column defaults
columnDefs = [
    {"field": "athlete"},
    {"field": "age", "filter": "agNumberColumnFilter", "maxWidth": 100},
    {"field": "country"},
    {
        "headerName": "Date",
        "filter": "agDateColumnFilter",
        "valueGetter": {"function": "d3.timeParse('%d/%m/%Y')(params.data.date)"},
        "valueFormatter": {"function": "params.data.date"},
    },
    {"field": "sport"},
    {"field": "total"},
]

app.layout = html.Div(
    [
        dcc.Markdown(
            "This grid has a number filter on the 'Age' column, a date filter on the date and a text filter on the other columns"
        ),
        dag.AgGrid(
             id="filter-options-example-simple",
            columnDefs=columnDefs,
            rowData=df.to_dict("records"),
            columnSize="sizeToFit",
            defaultColDef={"resizable": True, "sortable": True, "filter": True},
        ),
    ],
    style={"margin": 20},
)

if __name__ == "__main__":
    app.run(debug=True)

This grid has a number filter on the ‘Age’ column, a date filter on the date and a text filter on the other columns

Filters on Columns

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

The date filter uses d3.time-format. See the Rendering section for more information.
The code below shows some column definitions with filters set:

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' },

    # sets the date filter
      {
        "headerName": "Date",
        "filter": "agDateColumnFilter",
        "valueGetter": {"function": "d3.timeParse('%d/%m/%Y')(params.data.date)"},
        "valueFormatter": {"function": "params.data.date"},
    },
]

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.

# 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 },
]

Filter Parameters

Each filter can take additional filter parameters by setting 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 below- Apply, Clear, Reset and Cancel Buttons).

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
        }
    }
]

Filtering Animation

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

Relation to Quick Filter

Column filters work independently of Quick Filter. If a quick filter is applied along with a column filter, each filter type is considered and the row will only show if it passes both types.

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

Provided Filter UI

Each provided filter is displayed in a UI with optional buttons at the bottom.

Filter UI

Provided Filter Params

All the provided filters have the following parameters:

Apply, Clear, Reset and Cancel Buttons

Each of the provided filters can optionally include Apply, Clear, Reset and Cancel buttons.

When the Apply button is used, the filter is only applied once the Apply button is pressed. This is useful if the filtering operation will take a long time because the dataset is large, or if using server-side filtering (thus preventing unnecessary calls to the server). Pressing Enter is equivalent to pressing the Apply button.

The Clear button clears just the filter UI, whereas the Reset button clears the filter UI and removes any active filters for that column.

The Cancel button will discard any changes that have been made in the UI, restoring the state of the filter to match the applied model.

The buttons will be displayed in the order they are specified in the buttons array.

The example below demonstrates using the different buttons. It also demonstrates the relationship between the buttons and filter events. Note the following:

import dash_ag_grid as dag
from dash import Dash, html
import pandas as pd

app = Dash(__name__)

df = pd.read_csv(
    "https://raw.githubusercontent.com/plotly/datasets/master/ag-grid/olympic-winners.csv"
)

columnDefs = [
    {
        "field": "athlete",
        "filter": "agTextColumnFilter",
        "filterParams": {
            "buttons": ["reset", "apply"],
        },
    },
    {
        "field": "age",
        "maxWidth": 100,
        "filter": "agNumberColumnFilter",
        "filterParams": {
            "buttons": ["apply", "reset"],
            "closeOnApply": True,
        },
    },
    {
        "field": "country",
        "filter": "agTextColumnFilter",
        "filterParams": {
            "buttons": ["clear", "apply"],
        },
    },
    {
        "field": "year",
        "filter": "agNumberColumnFilter",
        "filterParams": {
            "buttons": ["apply", "cancel"],
            "closeOnApply": True,
        },
        "maxWidth": 100,
    },
    {"field": "sport"},
    {"field": "gold", "filter": "agNumberColumnFilter"},
    {"field": "silver", "filter": "agNumberColumnFilter"},
    {"field": "bronze", "filter": "agNumberColumnFilter"},
    {"field": "total", "filter": "agNumberColumnFilter"},
]

defaultColDef = {
    "flex": 1,
    "minWidth": 150,
    "filter": True,
}

app.layout = html.Div(
    [
        dag.AgGrid(id="apply-clear-example", rowData=df.to_dict("records"), columnDefs=columnDefs, columnSize="sizeToFit"),
    ]
)


if __name__ == "__main__":
    app.run(debug=True)

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.

Simple Filter Parts

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:

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 Name Option Key Supported Filters
Equals equals Text, Number, Date
Not Equals notEqual Text, Number, Date
Contains contains Text
Not Contains notContains Text
Starts With startsWith Text
Ends With endsWith Text
Less Than lessThan Number, Date
Less Than or Equal lessThanOrEqual Number
Greater Than greaterThan Number, Date
Greater Than or Equal greaterThanOrEqual Number
In Range inRange Number, Date
Blank blank Text, Number, Date
Not blank notBlank Text, Number, Date
Choose One empty Text, 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 filter types has the following default options and default selected option.

Filter Default List of Options Default Selected Option
Text Contains, Not Contains, Equals, Not Equals, Starts With, Ends With. Contains
Number Equals, Not Equals, Less Than, Less Than or Equal, Greater Than, Greater Than or Equal, In Range. Equals
Date Equals, Greater Than, Less Than, Not Equals, In Range. Equals

Data Updates

Grid data can be updated in a number of ways, including:

Example: Simple Filter Options

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

import dash_ag_grid as dag
from dash import Dash, html, dcc
import pandas as pd

app = Dash(__name__)

df = pd.read_csv(
    "https://raw.githubusercontent.com/plotly/datasets/master/ag-grid/olympic-winners.csv"
)


columnDefs = [
    {"field": "athlete"},
    {
        "field": "country",
        "filterParams": {
            "filterOptions": ["contains", "startsWith", "endsWith"],
            "defaultOption": "startsWith",
        },
    },
    {
        "field": "age",
        "filter": "agNumberColumnFilter",
        "filterParams": {
            "filterPlaceholder": "Age...",
            "alwaysShowBothConditions": True,
            "defaultJoinOperator": "OR",
        },
        "maxWidth": 100,
    },
]
defaultColDef = {
    "flex": 1,
    "minWidth": 150,
    "filter": True,
}


app.layout = html.Div(
    [
        dag.AgGrid(
            id="filter-options-example-1",
            rowData=df.to_dict("records"),
            columnDefs=columnDefs,
            columnSize="sizeToFit",
            defaultColDef=defaultColDef,
        ),
        dcc.Markdown("Grid with Header styled on filter", style={"marginTop": 30}),
        dag.AgGrid(
             id="filter-options-example-2",
            rowData=df.to_dict("records"),
            columnDefs=columnDefs,
            columnSize="sizeToFit",
            defaultColDef=defaultColDef,
            className="header-style-on-filter ag-theme-alpine",
        ),
    ]
)


if __name__ == "__main__":
    app.run(debug=True)

Grid with Header styled on filter

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 above, we’ve added some styling to ag-header-cell-filtered, so when you filter a column you will notice the column header change.

CSS

.ag-header-cell-filtered {
  background-color: #1b6d85 !important;
  color: #fff !important;
}

.ag-header-cell-filtered span {
  color: #fff !important;
}

Customizing Filter Placeholder Text

Filter placeholder text can be customized on a per-column basis using filterParams.filterPlaceholder within the grid option columnDefs. The example above has a custom placeholder in the Age column