Filtering Data
- Overview
- Filter Functions
- Managing Filters
- Initial Filter
- Column Header Filters
- Search Data
- Ajax Filtering
- Events
Overview
Tabulator allows you to filter the table data by any field in the data set.
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);
An optional fourth argument can be passed to the setFilter function to pass a params object to the filter function
table.setFilter("tags", "keywords", "red green blue", {matchAll:true});
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", "Steve");
Keywords
The keywords filter displays any rows with data containing any space separated words in the specified string (case insensitive)
table.setFilter("colors", "keywords", "red green blue"); //returns rows with a colors filed containing either the word "red", "green", or "blue"
This filter has two optional params:
- separator - the separator used between words (default " ")
- matchAll - the row must contain all the keywords to pass the filter
table.setFilter("colors", "keywords", "red green blue", {matchAll:true}); //returns rows with a colors filed containing ALL the words "red", "green" & "blue"
Starts With
The starts filter displays any rows with data that starts with the specified string. (case insensitive)
table.setFilter("name", "starts", "ste");
Ends With
The ends filter displays any rows with data that ends with the specified string. (case insensitive)
table.setFilter("name", "ends", "son");
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);
An optional fourth argument can be passed to the addFilter function to pass a params object to the filter function
table.setFilter("tags", "keywords", "red green blue", {matchAll:true});
Refresh Existing Filters
You can trigger a refresh of the current filters using the refreshFilter function. This function will cause the current filters to be run again and applied to the table data.
This is mainly useful when you are using custom filter functions that use variables from outside of Tabulator to determine what is filtered, when these variables change you can then call the refreshFilter function to update the existing filters.
table.refreshFilter();
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
It is possible to filter the table data directly from the column headers, by setting the headerFilter option in the column definition object for that column. This will cause an editor 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.
{title:"Name", field:"name", headerFilter:"input"} //show headerFilter using "input" editor
Header filters are based on the editors used by the edit module, allowing a wide range of different header filter types. To enable a header filter on a column, you should set the headerFilter option to the name of the built-in editor you wish to use. You can find a full list of editors in the Built In Editors documentation
Setting this option to true will cause an editor element matching the columns editor type to be used, The editor will be chosen using the same rules as the editor parameter, for more information on this see the Editing Data documentation.
{title:"Name", field:"name", editor:"input", headerFilter:true} //show header filter matching the cells 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 Editing Data documentation.
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}
Live Filter Delay
By default Tabulator will wait 300 milliseconds after a keystroke before triggering the filter. You can customise this delay by using the headerFilterLiveFilterDelay table setup option:
var table = new Tabulator("#example-table", { headerFilterLiveFilterDelay:600, //wait 600ms from last keystroke before triggering filter });
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 column's definition object.
var table = new Tabulator("#example-table", { 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"
Get Header Filter Value
You get the current header filter value of a column by calling the getHeaderFilterValue function, This function takes any of the standard column component look up options as its first argument.
var filterValue = table.getHeaderFilterValue("name"); //get the header filter value for the name column
Alternatively if you have the Column Component of the column containing the header filter, you can call the getHeaderFilterValue function directly on the component.
var filterValue = column.getHeaderFilterValue() //get the header filter value for this column
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 filterMode option to send the filter data to the server instead of processing it client side
var table = new Tabulator("#example-table", { filterMode:"remote", //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 dataSendParams 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.
Events
A range of events are available for tracking the progress of sorting. See the Filter Events section for more information.