search()
Search for data in the table.
Description
The ability to search a table for data is core to the concept of DataTables, as it allows data to be easily accessed by users. This method provides the ability to control the global search of a table through the API. The global search is performed across all searchable columns (see columns.searchable
to disable searching for certain columns). If data is found matching in any column, then the whole row is matched and shown in the result set. Searching on individual columns can be performed using the columns().search()
and column().search()
methods.
DataTables has a built in search algorithm referred to as "smart" searching and is designed to make searching the table data, easy to use for the end user. A smart search in DataTables provides the following abilities:
- Match words out of order. For example if you search for
Allan Fife
it would match a row containing the wordsAllan
andFife
, regardless of the order or position that they appear in the table. - Partial word matching. As DataTables provides on-the-fly filtering with immediate feedback to the user, parts of words can be matched in the result set. For example
All
will matchAllan
. - Preserved text. DataTables 1.10 adds the ability to search for an exact phrase by enclosing the search text in double quotes. For example
"Allan Fife"
will match only text which contains the phraseAllan Fife
. It will not matchAllan is in Fife
.
The smart search ability of DataTables is performed using a regular expression and can be enabled or disabled using the third parameter of this method. If you wish to use a custom regular expression, for example to perform whole word exact matching, you would need to enable the regular expression option (second parameter) and disable the smart search option (third parameter) to ensure that the two do not conflict. DataTables provides a utility method (DataTable.util.escapeRegex()
) to escape regular expression special characters, which can be useful if you mix user input with regular expressions.
Note that this search ability in DataTables is actually technically a filter since it is subtractive. However, we term search to avoid naming conflict with the filter()
helper method.
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 search()
method's returned object - for example table.search( 'Fred' ).draw();
. This is to provide the ability to queue multiple changes before performing a draw.
When using server-side processing, additional logic must be added at the server-side to handle regex search terms. Additionally, searching by functions is not possible, since the search function is client-side based.
Types
function search()
- Description:
Get the currently applied global search. If there is more than one table in the API's context, the search term of the first table will be returned. Use
table()
if you require the search term of a different table in the API's context.- Returns:
The currently applied global search. This may be an empty string if no search is applied.
function search( input [, options] )
- Description:
Set the global search to use on the table with configuration options. Call
draw()
to update the table's view once the search term has been setup.- Parameters:
Name Type Optional 1 string|RegExp|function
No Search to apply to the table.
As of DataTables 2, this parameter can be given as a regular expression or a function.
If working with a regular expression, be aware that the regex is applied to a single string with the search data from all searchable columns (double space joined).
In the case of a function the function is called for each row with three parameters which are passed in:
- The search string of data from all searchable columns in the table
- The row's original data object
- The row's data index
A boolean value should be returned:
true
to keep the row,false
to filter it out.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
DataTables.SearchOptions
for a description of all options. If an option is not given here, the value that it was set to for the previous search will be used.- Returns:
DataTables API instance
function search( input [, regex[ , smart[ , caseInsen ]]] )
- Description:
Set the global search to use on the table. Note that the signature above is preferred as of DataTables 2, as it provides additional options. This signature is retained for backwards compatibility.
- Parameters:
Name Type Optional 1 input
No Search to apply to the table. See the
input
parameter in the signature above for full details.2 regex
Yes - default:false Treat as a regular expression (
true
) or not (default,false
).3 smart
Yes - default:true Perform smart search (default,
true
) or not (false
). See below for a description of smart searching.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,
true
) or not (false
).- Returns:
DataTables API instance
Examples
Search the table using a custom input:
let table = new DataTable('#example');
// #myInput is a <input type="text"> element
$('#myInput').on('keyup', function () {
table.search(this.value).draw();
});
Custom search function:
let table = new DataTable('#example');
table.search((d) => d.includes('My search term')).draw();
// note that the above can also be rewritten as:
table
.search(function (d) {
return d.includes('My search term');
})
.draw();
Custom regex search:
let table = new DataTable('#example');
table.search(/\bTerm/i).draw();
Related
The following options are directly related and may also be useful in your application development.