columns().search()
Search for data in the selected columns.
Description
This method provides the ability to set a search across one or more columns. The search term provided will be checked against the data from the selected columns. As such, this method can be used as a global search across all columns (if they are selected), or a single column (i.e. column().search()). More commonly, this method will be used to provide a search across a sub-set of columns from the table.
DataTables' built in search search is referred to as "smart" searching and is designed to make searching the table data, easy to use for the end user. The smart search is used by default, although it has a number of configuration options that can be used to for fine grained control through the optional options parameter which takes a DataTable.SearchOptions object. For a full description of smart searching in DataTables, please refer to the documentation for search().
Note that this search ability in DataTables is actually technically a filter since it is subtractive. However, we term is a search to avoid naming overlap with the filter() helper method.
Furthermore, each subset of columns can have a single search term applied only when using this method or column().search(). For example, if the selector used for this method picks a single column, it would overlap with any search applied by the singular method (i.e. .columns(1).search(...) and .column(1).search(...) share the same search). If you wish to layer multiple search terms on the same subset of columns, please use column().fixed.search() / columns().fixed.search().
Please be aware that this method sets the search to apply to the table only - it does not actually perform the search. In order to have the search performed and the result shown, use the draw() method, which can be called simply as a chained method of the columns().search() method's returned object - for example table.columns( [0, 1] ).search( 'Fred' ).draw();. This is to provide the ability to queue multiple changes before performing a draw.
Types
columns().search()
Get the currently applied column search.
Returns:
string:
Api instance with the applied search terms for the selected columns in the result set.
Please note that prior to DataTables 3, this method would return a DataTables Api instance containing the search term for each of the selected columns. As the search is now shared over the selected columns, just the search value is returned.
columns().search( input [, options] )
Set the search term to use for the selected columns, with configuration options. Call draw() to update the table's view once the search term has been setup.
Parameters:
| Name | Type | Optional | |
|---|---|---|---|
| 1 | input | No | |
Search to apply to the column. As of DataTables 2, this parameter can be given as a regular expression or a function as well as the original string option. If working with a regular expression, the data given is the search data for the cells in column in question. In the case of a function the function is called for each row with two parameters which are passed in; the first is the search data for the cell in the row/column being search, and the second is the row's original data object. A boolean value should be returned: Note that if a regex or function is provided for this parameter, the following parameters are ignored. | |||
| 2 | options | No | |
Configuration options for how the search will be performed. See | |||
Returns:
DataTable.Api: DataTables API instance
columns().search( input [, regex[ , smart[ , caseInsen ]]] )
Set the search term for the columns from the selector. Note this doesn't actually perform the search, but rather queues it up - use draw() to perform the search and display the result.
Parameters:
| Name | Type | Optional | |
|---|---|---|---|
| 1 | input | No | |
The search term to apply. See the | |||
| 2 | regex | Yes - default:false | |
Treat as a regular expression ( | |||
| 3 | smart | Yes - default:true | |
Perform smart search (default, Note that to perform a smart search, DataTables uses regular expressions, so if enable regular expressions using the second parameter to this method, you will likely want to disable smart searching as the two regular expressions might otherwise conflict and cause unexpected results. | |||
| 4 | caseInsen | Yes - default:true | |
Do case-insensitive matching (default, | |||
Returns:
DataTable.Api: DataTables API instance
Examples
Search for a work in the selected columns:
var table = new DataTable('#myTable');
table
.columns('.status')
.search('Important')
.draw();Perform a search over a subset of columns:
let table = new DataTable('#example');
// Create an `input` element and bind an event to it
let input = DataTable.Dom.c('input')
.appendTo('body')
.on('keyup', function () {
table.columns([0, 1, 2, 3, 4]).search(this.value);
});Provide smart search options:
let table = new DataTable('#example');
// Create an `input` element and bind an event to it
let input = DataTable.Dom.c('input')
.appendTo('body')
.on('keyup', function () {
table
.columns([0, 1, 2, 3, 4])
.search(this.value, {
caseInsensitive: false
});
});Related
The following options are directly related and may also be useful in your application development.