DataTables logo
≡

DataTable.Api

DataTables API object instance.

Description

The DataTables API provides the ability to programmatically control one or more DataTable tables through the extensive array of methods that it implements. Many methods the API implements return an API instance themselves, providing the ability to chain methods, thus allowing the API to be both compact and very expressive. As such, we define this DataTable.Api data type to be clear when a method provides an API instance as its return value.

API structure

The API object is array-like (arrayLike) - i.e. it has a length property and elements in its result set can be accessed using JavaScript array notation ([]). In addition, it provides many (although not all) of the same methods as an array (for example push() and indexOf() are available). Please see the API manual page for an overview of using the DataTables API.

Accessing the API

New API instances can be created by:

  • new DataTable( selector, options ); - Initialise a new DataTable and return an API instance
  • new DataTable.Api( selector ); - Create a new API instance for an existing DataTable

The result from each is an instance of the DataTables API object which has the tables found by the selector in its context. In all three cases selector is a CSS selector.

As an example, the following will initially get an API instance to the DataTable #myTable, and then use the API to get some data from it:

const table = new DataTable.Api( '#myTable' );

// Get data from the first row
const data = table.rows().data()[0]; // same as row(0).data()

ES module

The API object is exported by DataTables and can be referenced as a named import (as of DataTables 3.0):

import { Api } from 'datatables.net';

const table = new DataTable.Api( '#myTable' );
// ...

If you are using TypeScript, the exported Api can also be used purely as a type if required.

Legacy jQuery API

If you are using DataTables with jQuery, you can access the DataTables API through:

  • $( selector ).DataTable(); - Create a new DataTable or fetch existing tables and return a DataTables API instance.
  • $( selector ).dataTable().api(); - DataTables jQuery constructor

It is important to note the difference between $( selector ).DataTable() and $( selector ).dataTable(). The former returns a DataTables API instance, while the latter returns a jQuery object. An api() method is added to the jQuery object so you can easily access the API, but the jQuery object can be useful for manipulating the table node, as you would with any other jQuery instance (such as using addClass() etc).

As an example, the following uses jQuery to select #myTable and then uses the returned DataTables API instance to perform a search on the table.

var table = $('#myTable').DataTable();

// Search for a data point
table.search( 'Fiona' ).draw();

Further information

Use the following resources to explore the DataTables API further:

  • API manual - detailed usage and explanation of the API terminology
  • API reference - list of all API methods available
  • API plug-ins - community provided plug-ins to extend the API's capabilities