DataTables API object instance.


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 DataTables.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, in that it has a length property, elements in its result set can be accessed using Javascript array notation ([]) and it provides many (although not all) of the same methods as an array (for example push() and indexOf()).

Accessing the API

New API instances can be created in one of three ways:

  • $( selector ).DataTable(); - DataTables constructor
  • $( selector ).dataTable().api(); - DataTables jQuery constructor
  • new $.fn.dataTable.Api( selector ); - Direct initialisation

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 jQuery selector.

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

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

// Search for a data point
table.search( 'Fiona' ).draw();
$( selector ).dataTable(); example
var table = new DataTable('#myTable').api();

// Jump to the next page of data
new $.fn.dataTable.Api( selector );
var table = new $.fn.dataTable.Api( '#myTable' );

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

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