Quick Filters

Quick Filter is a piece of text given to the grid (typically the user will type it in somewhere in your application)
that is used to filter rows by comparing against the data in all columns. This can be used in addition to
column-specific filtering.

Setting the Quick Filter

You can set the Quick Filter text using the Grid Option 'quickFilterText':

dashGridOptions = {'quickFilterText': 'Tony France'}

The provided Quick Filter text will be split into words, and each word will be compared against the row. A word matches
the row if the string value of any columns contains the word (the check is case-insensitive). All words must match the
row for it to be included. For example, if the text is “Tony France”, the Quick Filter will only include rows with
both “Tony” AND “France” in them.

Overriding the Quick Filter Value

If your data contains complex objects, the Quick Filter will end up comparing against [object Object] instead of
searchable string values. In this case you will need to implement getQuickFilterText to extract a searchable string
from your complex object.

Alternatively, you might want to format string values specifically for searching (for example, replace accented
characters in strings, or remove commas from numbers).

The Quick Filter will work ‘out of the box’ in most cases, so you should only override the Quick Filter value if you
have a particular problem to resolve.

View the JavaScript function used for this example

This JavaScript function must be added to the dashAgGridFunctions.js file in the assets folder.
See JavaScript Functions
for more information.

var dagfuncs = (window.dashAgGridFunctions = window.dashAgGridFunctions || {});

dagfuncs.getMedalString = function ({gold, silver, bronze}) {
    const goldStr = gold > 0 ? `Gold: ${gold} ` : '';
    const silverStr = silver > 0 ? `Silver: ${silver} ` : '';
    const bronzeStr = bronze > 0 ? `Bronze: ${bronze}` : '';
    return goldStr + silverStr + bronzeStr;
};

View Custom Cell Renderer used for this example

This JavaScript function must be added to the dashAgGridComponentFunctions.js file in the assets folder.
See Custom Components for more
information.

var dagcomponentfuncs = (window.dashAgGridComponentFunctions = window.dashAgGridComponentFunctions || {});

dagcomponentfuncs.MedalRenderer = function (params) {
    return dagfuncs.getMedalString(params.value);
};

Quick Filter Cache

By default, the Quick Filter checks each column’s value, including running value getters if present, every time the
Quick Filter is executed. If your data set is large, you may wish to enable the Quick Filter cache by setting the Grid
Option:

dashGridOptions = {'cacheQuickFilter': True}

When the cache is enabled, a quickFilterAggregateText property is generated for each node by concatenating all the
values for each column. For example, a table with columns of “Employee Name” and “Job” could have a row with Quick
Filter text of 'NIALL CROSBY\nCOFFEE MAKER'. The grid then performs a simple string search, so if you search
for 'Niall', it will find our example text. Joining all the column values into one string gives a performance boost.
The values are joined after the Quick Filter is requested for the first time and stored in the rowNode - the original
data that you provide is not changed.

Reset Cache Text

When in use, the quickFilterAggregateText property can be manually reset in one of the following ways:

Updating Data, Cell Editing,
Excluding/Including Hidden Columns from
the Quick Filter, and Updating Column Definitions
will automatically reset the cache text on any affected Row Nodes.

Note that the gridAPI can be used through Clientside Callbacks.

The following example demonstrates the difference using the Quick Filter Cache or not. The grid works very fast even
when the cache is turned off, so you probably don’t need it for small data sets. For large data sets (for example, over
10,000 rows), turning the cache on will improve Quick Filter speed. Tweaking the cacheQuickFilter option in the
example allows both modes to be experimented with:

A Clientside Callback is used to get the Quick Filter Cache and
display cache of the 5 first data rows below the Grid.

Another Clientside Callback is used to reset the quickFilterAggregateText property using the button ‘Reset Cache’.

View the Clientside Callbacks used for this example.

These Clientside Callbacks must be added to any *.js file in the assets folder.
See Clientside Callbacks for more information.

window.dash_clientside = window.dash_clientside || {};

window.dash_clientside.quickFilter = {

    wait: (n) => new Promise((resolve) => setTimeout(resolve, n)),

    getOutput: (gridAPI) => {
        let output = [];
        gridAPI.forEachNode((rowNode, index) => {
            let cache;
            if (index < 5) {
                cache = rowNode.quickFilterAggregateText
                output.push('Row ' + index + ': ' + (cache ? cache.replace(/\n/g, '\\n') : 'undefined'))
            }
        });
        return output.join('\n')
    },

    getQuickFilterCache: async function (quickFilter, gridId) {
        const gridAPI = await dash_ag_grid.getApiAsync(gridId)

        // wait for the cache to be updated
        await window.dash_clientside.quickFilter.wait(500)
        return window.dash_clientside.quickFilter.getOutput(gridAPI)
    },

    resetQuickFilterCache: async function (click) {
        const gridAPI = await dash_ag_grid.getApiAsync('quick-filter-cache')
        gridAPI.resetQuickFilter()

        // wait for the cache to be updated
        await window.dash_clientside.quickFilter.wait(500)
        return window.dash_clientside.quickFilter.getOutput(gridAPI)
    },
}

Include Hidden Columns

By default, the Quick Filter will only check visible column values. If you want to check hidden column values, then you
can set:

dashGridOptions = {'includeHiddenColumnsInQuickFilter': True}

Note that if you have a large number of hidden columns then this can have a performance impact.

The following example shows the result enabling or not the includeHiddenColumnsInQuickFilter parameter.
A hidden column with only 'hidden' values has been added to the grid.

Filtering with michael phelps hidden and:

Quick Filter Parser

By default, the Quick Filter splits the text into a list of words which are then compared against each row. You may want
to override this behaviour, for example to allow using quotes to search for exact string values,
like the example below. This is
possible by providing a quickFilterParser function. Note that the value passed to the parser will have already been
converted to upper case.

The following snippet allows to split by space (like by default) and ‘,’ for the words to search:

# allows to split the Quick Filter text by space (default) and ',' for the words to search
dashGridOptions = {"quickFilterParser": {"function": r"params.split(/[\s,]+/)"}}

Quick Filter Matcher

The default behaviour of the Quick Filter is to check whether every search term in the parsed Quick Filter text appears
in the Quick Filter Value for any column.
The matching logic can be overridden by providing a quickFilterMatcher, for example, to perform searches via regular
expressions.

The rowQuickFilterAggregateText parameter passed to the matcher function is a concatenation of all the Quick Filter
Values (using the Quick Filter Cache if enabled). Note
that this value will be upper case.

This JavaScript function must be added to the dashAgGridFunctions.js file in the assets folder.
See JavaScript Functions
for more information and
the example below.

var dagfuncs = (window.dashAgGridFunctions = window.dashAgGridFunctions || {});

dagfuncs.quickFilterMatcher = (quickFilterParts, rowQuickFilterAggregateText) => {
    return quickFilterParts.every(part => rowQuickFilterAggregateText.match(part));
}

dashGridOptions = {
    # allows to use regex in quick search, like 2[012] matching Age 20, 21 and 22
    "quickFilterMatcher": {"function": "quickFilterMatcher"}
}

Example: Quick Filter Parser and Matcher

A quickFilterParser is defined to allow exact searches using double-quotes, for example:

A quickFilterMatcher is also defined to allow regular expressions to be entered, for example, 2[012] will match Age
20, 21 and 22.

Server Side Data

Quick Filters only make sense with client-side data (for example, when using
the Client-Side Row Model). For the other row models you would
need to implement your own server-side filtering to replicate Quick Filter functionality.

API Reference

Grid Options

Column Properties