Filtering Data

• Overview
• Filter Functions
  • Built In Filters
  • Custom Filters
  • Complex Filtering
• Managing Filters
• Initial Filter
• Column Header Filters
• Search Data
• Ajax Filtering
• Callbacks

Overview Demo

Tabulator allows you to filter the table data by any field in the data set.

<div id="example-table"></div>

//Custom filter example
function customFilter(data){
    return data.car && data.rating < 3;
}

//Trigger setFilter function with correct parameters
function updateFilter(){

    var filter = $("#filter-field").val() == "function" ? customFilter : $("#filter-field").val();

    if($("#filter-field").val() == "function" ){
        $("#filter-type").prop("disabled", true);
        $("#filter-value").prop("disabled", true);
    }else{
        $("#filter-type").prop("disabled", false);
        $("#filter-value").prop("disabled", false);
    }

    table.setFilter(filter, $("#filter-type").val(), $("#filter-value").val());
}

//Update filters on value change
$("#filter-field, #filter-type").change(updateFilter);
$("#filter-value").keyup(updateFilter);

//Clear filters on "Clear Filters" button click
$("#filter-clear").click(function(){
    $("#filter-field").val("");
    $("#filter-type").val("=");
    $("#filter-value").val("");

    table.clearFilter();
});

//Build Tabulator
var table = new Tabulator("#example-table", {
    height:"311px",
    layout:"fitColumns",
    columns:[
        {title:"Name", field:"name", width:200},
        {title:"Progress", field:"progress", formatter:"progress", sorter:"number"},
        {title:"Gender", field:"gender"},
        {title:"Rating", field:"rating", formatter:"star", align:"center", width:100},
        {title:"Favourite Color", field:"col"},
        {title:"Date Of Birth", field:"dob", align:"center", sorter:"date"},
        {title:"Driver", field:"car", align:"center", formatter:"tickCross"},
    ],
});

To set a filter you need to call the setFilter method, passing the field you wish to filter, the comparison type and the value to filter for.

This function will replace any exiting filters on the table with the specified filters.

table.setFilter("age", ">", 10);

Filter Functions

Built In Filters

Tabulator comes with a number of filter comparison types including:

Note: For a guide to adding your own filters to this list, have a look at the Extending Tabulator section.

Equal

The = filter displays only rows whith data that exactly matches the filter value

table.setFilter("name", "=", "Steve");

Not Equal

The != filter displays only rows whith data that does not exactly match the filter value

table.setFilter("name", "!=", "Steve");

Like

The like filter displays any rows with data that contains the specified string anywhere in the specified field. (case insensitive)

table.setFilter("name", "like", "teve");

Less Than

The < filter displays rows with a value less than the filter value

table.setFilter("age", "<", 10);

Less Than Or Equal To

The <= filter displays rows with a value less than or equal to the filter value

table.setFilter("age", "<=", 10);

Greater Than

The > filter displays rows with a value greater than the filter value

table.setFilter("age", ">", 10);

Greater Than Or Equal To

The >= filter displays rows with a value greater than or equal to the filter value

table.setFilter("age", ">=", 10);

In Array

The in filter display sany rows with a value in the filter value array passed to the filter, values must be of the same type as they are in the array

table.setFilter("age", "in", ["steve", "bob", "jim"]);

Regex

The regex displays rows that match a provided regex

table.setFilter("age", "regex", /[a-z]/);

Custom Filter Functions

If you want to perform a more complicated filter then you can pass a callback function to the setFilter method, you can also pass an optional second argument, an object with parameters to be passed to the filter function.

function customFilter(data, filterParams){
    //data - the data for the row being filtered
    //filterParams - params object passed to the filter

    return data.name == "bob" && data.height < filterParams.height; //must return a boolean, true if it passes the filter.
}

table.setFilter(customFilter, {height:3});

Applying Multiple Filters

If you wish to apply multiple filters then you can pass an array of filter objects to this function, the data will then have to pass all filters to be displayed in the table.

table.setFilter([
    {field:"age", type:">", value:52}, //filter by age greater than 52
    {field:"height", type:"<", value:142}, //and by height less than 142
    {field:"name", type:"in", value:["steve", "bob", "jim"]}, //name must be steve, bob or jim
]);

Filters will remain in effect until they are cleared, including during setData calls.

Complex Filtering

The filtering example above shows how to apply a series of filters to some table data and show only the data where all the filters are matched, but what if you want to use an OR type comparison.

To do this you can put an array of filters inside your filter array, and any filters in this second array will use an OR comparison type.

The example below applies a filter that will let through rows with a age of greater than 52 AND (either a height of less than 142 OR with the name steve)

table.setFilter([
    {field:"age", type:">", value:52}, //filter by age greater than 52
    [
        {field:"height", type:"<", value:142}, //with a height of less than 142
        {field:"name", type:"=", value:"steve"}, //or a name of steve
    ]
]);

You can nest OR filter arrays several levels deep to build up complex filters.

Managing Filters

There are a number of additional methods that can be called to customise your filtering experience

Add Filter to Existing Filters

If you want to add another filter to the existing filters then you can call the addFilter function:

table.addFilter("age", ">", 22);

Remove One of Many Existing Filters

If you want to remove one filter from the current list of filters you can use the removeFilter function:

table.removeFilter("age", ">", 22);

Get Current Filters

You can retrieve an array of the current programtic filters using the getFilters function, this will not include any of the header filters:

var filters = table.getFilters();

This will return an array of filter objects

[
    {field:"age", type:">", value:52}, //filter by age greater than 52
    {field:"height", type:"<", value:142}, //and by height less than 142
]

To include header filters in the returend array pass an option argument of true to the getFilters function:

var allFilters = table.getFilters(true);

Get Header Filters

If you just want to retrieve the current header filters, you can use the getHeaderFilters function:

var headerFilters = table.getHeaderFilters();

Clear All Filters

To remove all filters from the table, use the clearFilter function.

table.clearFilter();

This will clear all programmatically set filters, if you wisht to clear all header filters as well pass an argument of true to this function.

table.clearFilter(true);

Clear Header Filters

To remove just the header filters, leaving the programatic filters in place, use the clearHeaderFilter function.

table.clearHeaderFilter();

Initial Filter

When the table is first created it can be defined with an initial set of filters. These can be set using the initialFilter option. This will take the same filter array as the setFilter function. (see Filter Functions for more details)

var table = new Tabulator("#example-table", {
    initialFilter:[
        {field:"color", type:"=", value:"red"}
    ],
});

Header Filtering Demo

It is possible to filter the table data directly from the column headers, by setting the headerFilter parameter in the column definition object for that column.

{title:"Name", field:"name", headerFilter:true} //show header filter matching the cells editor

Setting this parameter to true will cause an editor element matching the columns editor type to be displayed in the header below the column title, and will allow the user to filter data in the table by values in that column. The editor will be chosen using the same rules as the editor parameter, for more information on this see the Manipulating Data section.

Alternatively you can pass a string to this parameter containing any of the standard editors listed in the Manipulating Data section

{title:"Name", field:"name", headerFilter:"input"} //show headerFilter using "input" editor

You can also pass a custom editor function to this parameter in the same way as you would for column editor. For more information see the Manipulating Data section.

You can pass an optional additional parameter with the header filter, headerFilterParams that should contain an object with additional information for configuring the header filter element. This will be passed to the editor in the column header instead of the editorParams property.

{title:"Name", field:"name", headerFilter:"input", headerFilterParams:{initial:"Steve Bobberson"}} //show headerFilter using "input" editor

Params Lookup Function

If you want to dynamically generate the headerFilterParams at the time the header filter is created, you can pass a function into the property that should return the params object.

//define lookup function
function paramLookup(cell){
    //do some processing and return the param object
    return {param1:"green"};
}

//column definition
{title:"Name", field:"name", headerFilter:"input", headerFilterParams:paramLookup}

Note: At present, the progress and star editors are not available as header filters.

Header Filters and Programmatic Filters

Header filters and programatic filters can be set independently allowing you to use a header filter to further restrict the rows shown in an already filtered data set.

Initial Header Filter Values

When the table is first created it can be defined with an initial set of header filter values. These can be set using the initialHeaderFilter option. This will take an array of objects with the value for the filter and the column header it should be set on.

var table = new Tabulator("#example-table", {
    initialHeaderFilter:[
        {field:"color", value:"red"} //set the initial value of the header filter to "red"
    ],
});

Real Time Filtering

If an input element is used as the filter element, the table will be filtered in real time as the user types in the input element. To prevent exessive redrawing of the table Tabulator will wait 300 milliseconds after the user has finished typing before triggering the filter, this ensures that the table is not redrawn for every character typed by the user.

Note: If the input has a type attribute value of text it will be automatically changed to search to give the user the option to clear the input text.

If you would prefer that the input element behave like a standard editor without live updating the table, you can set the headerFilterLiveFilter column definition property to false

{title:"Name", field:"name", headerFilter:"input", headerFilterLiveFilter:false}

Empty Header Filters

By default Tabulator will clear the filter when it considers the header filter value to be empty, in the case of most filters that is if the value is undefined, null, or "", or in the case of check boxes that is if the value is not either true or false.

If you are using a custom filter or want to alter what an existing filter considers empty, you can pass a function to the headerFilterEmptyCheck column definition property. This function will be passed in the value of the filter as an argument and should return a boolean where true represents an empty filter

{title:"Allowed", field:"allowed", headerFilter:"tick", headerFilterEmptyCheck:function(value){
    return !value; //only filter when the value is true
}},

Filter Comparison Types

By default Tabulator will try and match the comparison type to the type of element used for the header filter.

Standard input elements will use the "like" filter, this allows for the matches to be displayed as the user types.

For all other element types (select boxes, check boxes, input elements of type number) an "=" filter type is used.

If you want to specify the type of filter used you can pass it to the headerFilterFunc option in the column definition object. This will take any of the standard filters outlined above or a custom function:

{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:"<="} //show only rows with an age less than or equal the entered value

When using a custom filter function for a header filter, the arguments passed to the function will be slightly different from a normal custom filter function

function customHeaderFilter(headerValue, rowValue, rowData, filterParams){
    //headerValue - the value of the header filter element
    //rowValue - the value of the column in this row
    //rowData - the data for the row being filtered
    //filterParams - params object passed to the headerFilterFuncParams property

    return rowData.name == filterParams.name && rowValue < headerValue; //must return a boolean, true if it passes the filter.
}

//column definition object in table constructor
{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:customHeaderFilter, headerFilterFuncParams:{name:"bob"}}

As the above example demostrates it is possible to pass additional parameters to the custom filter function by passing an object to the headerFilterFuncParams option in the column definition.

{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:customHeaderFilter, headerFilterFuncParams:{name:"bob"}}

Placeholder Text

The default placeholder text used for input elements can be set using the headerFilterPlaceholder option in the table definition

var table = new Tabulator("#example-table", {
    headerFilterPlaceholder:"filter data...", //set column header placeholder text
});

To set the placeholder text on a per column basis you can use the headerFilterPlaceholder option in the column's definition object.

var table = new Tabulator("#example-table", {
    headerFilterPlaceholder:"filter data...", //set column header placeholder text
    columns:[
        {title:"Name", field:"name", headerFilter:true, headerFilterPlaceholder:"Find a Person..."} //set placeholder text on name column header filter
    ]
});

Set Header Filter Value

You can programmatically set the header filter value of a column by calling the setHeaderFilterValue function, This function takes any of the standard column component look up options as its first parameter, with the value for the header filter as the second option

table.setHeaderFilterValue("name", "Steve"); //set header filter for name column to  "steve"

Focus On Header Filter

You can programmatically set the focus on a header filter element by calling the setHeaderFilterFocus function, This function takes any of the standard column component look up options as its first parameter

table.setHeaderFilterFocus("name"); //focus on the header filter for the name column

Search Data

Search functions allow you to retrieve data using filters, exactly like those used by the setFilter function, any matching data or row components are then returned.

Search for Row Components

The searchRows function allows you to retrieve an array of row components that match any filters you pass in. it accepts the same arguments as the setFilter function.

var rows = table.searchRows("age", ">", 12);//get row components for all rows with an age greater than 12

Search for Row Data

The searchData function allows you to retrieve an array of table row data that match any filters you pass in. it accepts the same arguments as the setFilter function.

var data = table.searchData("age", ">", 12);//get row data for all rows with an age greater than 12

Ajax Filtering

If you would prefer to filter your data server side rather than in Tabulator, you can use the ajaxFiltering option to send the filter data to the server instead of processing it client side

var table = new Tabulator("#example-table", {
    ajaxFiltering:true, //send filter data to the server instead of processing locally
});

An array of filters objects will then be passed in the filters parameter of the request, the name of this parameter can be set in the paginationDataSent option, in the pagination module.

The array of filter objects will take the same form as those returned from the getFilters function:

[
    {field:"age", type:">", value:52}, //filter by age greater than 52
    {field:"height", type:"<", value:142}, //and by height less than 142
]

If a custom filter function is being used then the type parameter will have a value of "function".

If the table is not currently filtered then the array will be empty.

Callbacks

A range of callbacks are available for tracking progress of filtering. See the Filter Callbacks section for more information.