search()

Since: DataTables 1.10

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 words Allan and Fife, 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 match Allan.
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 phrase Allan Fife. It will not match Allan 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:: string

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`	`input`	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`	`DataTables.SearchOptions`	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

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`	`string`, `RegExp`, `function`	No
	Search to apply to the table. See the `input` parameter in the signature above for full details.
2	`regex`	`boolean`	Yes - default:false
	Treat as a regular expression (`true`) or not (default, `false`).
3	`smart`	`boolean`	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`	`boolean`	Yes - default:true
	Do case-insensitive matching (default, `true`) or not (`false`).

Returns:

DataTables.Api

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();

The following options are directly related and may also be useful in your application development.

API

Options