{hero}

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:

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:
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:
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.