Events

It can often be useful to know when DataTables or one of its extensions has performed a particular operation, for example a page draw, so other dependent elements can be updated to take account of the change. To provide this ability, DataTables will fire custom DOM events which can be listened for, and then acted upon, using either the on() method or jQuery's on() method. DataTables's custom events work in exactly the same way as standard DOM events, and allow event driven actions, which is particularly useful for plug-ins.

For a full list of the events that DataTables and its extensions will trigger, please refer to the event reference documentation.

Listening for events

As noted above, you can use either the on() or jQuery's on() method to listen for events. on() works in exactly the same way as $().on(), with provision for namespaces and multiple events.

Please be aware that all DataTables events are triggered with the dt namespace. 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 (when using on() the namespace is automatically appended if required). Because of the way namespaces work in jQuery, you can use the dt namespace and your own custom namespace(s) if you wish to use a namespace.

For example, to listen for the draw event in a DataTable:

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

table.on( 'draw', function () {
    alert( 'Table redrawn' );
} );

This could also be written as:

$('#example').on( 'draw.dt', function () {
    alert( 'Table redraw' );
} );

Note the use of the dt namespace when using the jQuery on() method, while the on() method will automatically append the namespace for you.

Removing events

As with $().on() DataTables events can be removed with off() and $().off(). It is important to remove events from objects which no longer exist (before they are destroyed) to allow the Javascript engine's garbage collector to release the memory allocated for the events and the objects it has attached to.

Further to this, a single event can be listened for with one() or $().one(), where the event handler will be removed immediately after the event has been triggered for the first time.

Bubbling

As with typical DOM events, the DataTables custom events bubble up through the document, so you can listen for events using the delegate form of $().on() or on other elements which are higher up the DOM tree.

This can be useful, for example, to know when a new DataTable has been created, which can be listened for using the init event thus:

$(document).on( 'init.dt', function ( e, settings ) {
    var api = new $.fn.dataTable.Api( settings );

    console.log( 'New DataTable created:', api.table().node() );
} );

Similarly, this method could also be useful with the xhr event which will let you know what JSON data was returned from the server from the last DataTables initiated Ajax query.

A full list of the events that DataTables and its extensions can trigger is available in the event reference documentation.