jQuery

DataTables' roots are deeply entwined with jQuery. jQuery shaped much of web development and, perhaps more importantly, browser development, providing a simple-to-use API for DOM manipulation and events. Indeed, it is still one of the most widely used libraries on the web.

DataTables had a hard dependency on jQuery, until the release of DataTables 3, at which point DataTables had zero external dependencies. Many hundreds of thousands of sites use DataTables together with jQuery, and although DataTables no longer requires jQuery, it still will operate with jQuery in exactly the same way as it did with earlier versions, helping to ensure seamless migration to DataTables 3.

The documentation on this page discusses how DataTables can be used with jQuery. Please note that the global DataTable object can be used on a page with jQuery without any problems - you can select whether to access DataTables via its jQuery harness, or directly, as works best for your workflow. More specifically:

$.fn.dataTable === DataTable

Installation

Install DataTables as normal and DataTables will automatically detect if jQuery is already available on the page (from the global jQuery variable being present). If it is, DataTables will attach itself as a jQuery plugin.

CDN / script tags

If you are loading DataTables using script tags from the CDN or from local files, make sure you load jQuery first, then DataTables - e.g.:

<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
<script src="https://cdn.datatables.net/v/dt/dt-3.0.0/datatables.min.js"></script>

This will ensure that DataTables can "see" jQuery and will register itself.

ES Modules

If you are using the ESM loading mechanism for your Javascript and wish to use jQuery with DataTables, you need to make use of the DataTable.use() method to tell DataTables about jQuery, as it does not automatically include jQuery and jQuery is not automatically available globally in ESM.

To do this, follow this pattern:

import jQuery from 'jquery';
import DataTable from 'datatables.net-dt';

DataTable.use(jQuery);

new DataTable('#myTable', {
    // config options...
});

// or

jQuery('#myTable').DataTable({
    // config options...
});

Initialisation

As DataTables will attach itself as a jQuery plugin, you can initialise DataTables from a jQuery instance:

let table = $('#myTable').DataTable({
    // options
});

The $().DataTable() method will return a DataTables API instance, allowing manipulation of the table (just the same as new DataTable()).

DataTables will also register a $().dataTable() plugin (lower case "D") with jQuery. This will create a DataTables, and options can be passed as the first parameter to the function, but the return value will be a jQuery instance, rather than the DataTables API. This can be useful for manipulating the table node, as you would with any other jQuery instance (such as using addClass(), etc.).

API

When using the jQuery interface for DataTables, the DataTables API can be accessed through any of the following methods:

• The return from $().DataTable() (which allows section of existing tables as well)
• Creating an API instance with new $.fn.dataTable.Api( selector );
• Or the normal method of new DataTable.Api( selector );

Events

When working with events, DataTables will make use of the jQuery event system in place of its own to ensure full compatibility. You can make use of on(), one() and off() to listen for DataTables events as normal.

It is also possible to listen for DataTables events using jQuery directly, but to do so, you must add a dt namespace to the event name - e.g., listening for init on the body element to be notified when any new DataTable is initialised:

$('body').on('init.dt', function () {
    console.log('A new DataTable was initialised');
});

This namespacing of events is to prevent clashes with custom events triggered by other Javascript libraries. As such, you should append .dt to the name of the event(s) that you are listening for (namespaces are handled automatically if you use the DataTables API methods, e.g. on()).