DataTables logo DataTables

This site contains the legacy documentation for DataTables v1.9 and earlier for reference only.
DataTables 1.9 was End Of Life in 2014. Do not use it for new work.
The current release of DataTables can always be found on DataTables.net.

Callbacks

During your use and integration of DataTables into your own software, there might be times when you wish to know when a certain event has occurred, allowing you to take appropriate action for that event. This might include modifying a table row/cell, or simply updating an information display every time the table is redrawn.

fnCookieCallback
Show details

Customise the cookie and / or the parameters being stored when using DataTables with state saving enabled. This function is called whenever the cookie is modified, and it expects a fully formed cookie string to be returned. Note that the data object passed in is a Javascript object which must be converted to a string (JSON.stringify for example).
Default:
Type: function
Code example: 
   $(document).ready( function () {
     $('#example').dataTable( {
       "fnCookieCallback": function (sName, oData, sExpires, sPath) {
         // Customise oData or sName or whatever else here
         return sName + "="+JSON.stringify(oData)+"; expires=" + sExpires +"; path=" + sPath;
       }
     } );
   } );
fnCreatedRow
Show details

This function is called when a TR element is created (and all TD child elements have been inserted), or registered if using a DOM source, allowing manipulation of the TR element (adding classes etc).
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "fnCreatedRow": function( nRow, aData, iDataIndex ) {
         // Bold the grade for all 'A' grade browsers
         if ( aData[4] == "A" )
         {
           $('td:eq(4)', nRow).html( 'A' );
         }
       }
     } );
   } );
fnDrawCallback
Show details

This function is called on every 'draw' event, and allows you to dynamically modify any aspect you want about the created DOM.
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "fnDrawCallback": function( oSettings ) {
         alert( 'DataTables has redrawn the table' );
       }
     } );
   } );
fnFooterCallback
Show details

Identical to fnHeaderCallback() but for the table footer this function allows you to modify the table footer on every 'draw' even.
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "fnFooterCallback": function( nFoot, aData, iStart, iEnd, aiDisplay ) {
         nFoot.getElementsByTagName('th')[0].innerHTML = "Starting index is "+iStart;
       }
     } );
   } )
fnFormatNumber
Show details

When rendering large numbers in the information element for the table (i.e. "Showing 1 to 10 of 57 entries") DataTables will render large numbers to have a comma separator for the 'thousands' units (e.g. 1 million is rendered as "1,000,000") to help readability for the end user. This function will override the default method DataTables uses.
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "fnFormatNumber": function ( iIn ) {
         if ( iIn < 1000 ) {
           return iIn;
         } else {
           var 
             s=(iIn+""), 
             a=s.split(""), out="", 
             iLen=s.length;
           
           for ( var i=0 ; i<iLen ; i++ ) {
             if ( i%3 === 0 && i !== 0 ) {
               out = "'"+out;
             }
             out = a[iLen-i-1]+out;
           }
         }
         return out;
       };
     } );
   } );
fnHeaderCallback
Show details

This function is called on every 'draw' event, and allows you to dynamically modify the header row. This can be used to calculate and display useful information about the table.
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "fnHeaderCallback": function( nHead, aData, iStart, iEnd, aiDisplay ) {
         nHead.getElementsByTagName('th')[0].innerHTML = "Displaying "+(iEnd-iStart)+" records";
       }
     } );
   } )
fnInfoCallback
Show details

The information element can be used to convey information about the current state of the table. Although the internationalisation options presented by DataTables are quite capable of dealing with most customisations, there may be times where you wish to customise the string further. This callback allows you to do exactly that.
Default:
Type: function
Code example: 
   $('#example').dataTable( {
     "fnInfoCallback": function( oSettings, iStart, iEnd, iMax, iTotal, sPre ) {
       return iStart +" to "+ iEnd;
     }
   } );
fnInitComplete
Show details

Called when the table has been initialised. Normally DataTables will initialise sequentially and there will be no need for this function, however, this does not hold true when using external language information since that is obtained using an async XHR call.
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "fnInitComplete": function(oSettings, json) {
         alert( 'DataTables has finished its initialisation.' );
       }
     } );
   } )
fnPreDrawCallback
Show details

Called at the very start of each table draw and can be used to cancel the draw by returning false, any other return (including undefined) results in the full draw occurring).
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "fnPreDrawCallback": function( oSettings ) {
         if ( $('#test').val() == 1 ) {
           return false;
         }
       }
     } );
   } );
fnRowCallback
Show details

This function allows you to 'post process' each row after it have been generated for each table draw, but before it is rendered on screen. This function might be used for setting the row class name etc.
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "fnRowCallback": function( nRow, aData, iDisplayIndex, iDisplayIndexFull ) {
         // Bold the grade for all 'A' grade browsers
         if ( aData[4] == "A" )
         {
           $('td:eq(4)', nRow).html( 'A' );
         }
       }
     } );
   } );
fnServerData
Show details

This parameter allows you to override the default function which obtains the data from the server ($.getJSON) so something more suitable for your application. For example you could use POST data, or pull information from a Gears or AIR database.
Default:
Type: function
Code example: 
   // POST data to server
   $(document).ready( function() {
     $('#example').dataTable( {
       "bProcessing": true,
       "bServerSide": true,
       "sAjaxSource": "xhr.php",
       "fnServerData": function ( sSource, aoData, fnCallback, oSettings ) {
         oSettings.jqXHR = $.ajax( {
           "dataType": 'json', 
           "type": "POST", 
           "url": sSource, 
           "data": aoData, 
           "success": fnCallback
         } );
       }
     } );
   } );
fnServerParams
Show details

It is often useful to send extra data to the server when making an Ajax request - for example custom filtering information, and this callback function makes it trivial to send extra information to the server. The passed in parameter is the data set that has been constructed by DataTables, and you can add to this or modify it as you require.
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "bProcessing": true,
       "bServerSide": true,
       "sAjaxSource": "scripts/server_processing.php",
       "fnServerParams": function ( aoData ) {
         aoData.push( { "name": "more_data", "value": "my_value" } );
       }
     } );
   } );
fnStateLoad
Show details

Load the table state. With this function you can define from where, and how, the state of a table is loaded. By default DataTables will load from its state saving cookie, but you might wish to use local storage (HTML5) or a server-side database.
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "bStateSave": true,
       "fnStateLoad": function (oSettings) {
         var o;
         
         // Send an Ajax request to the server to get the data. Note that
         // this is a synchronous request.
         $.ajax( {
           "url": "/state_load",
           "async": false,
           "dataType": "json",
           "success": function (json) {
             o = json;
           }
         } );
         
         return o;
       }
     } );
   } );
fnStateLoadParams
Show details

Callback which allows modification of the saved state prior to loading that state. This callback is called when the table is loading state from the stored data, but prior to the settings object being modified by the saved state. Note that for plug-in authors, you should use the 'stateLoadParams' event to load parameters for a plug-in.
Default:
Type: function
Code example: 
   // Remove a saved filter, so filtering is never loaded
   $(document).ready( function() {
     $('#example').dataTable( {
       "bStateSave": true,
       "fnStateLoadParams": function (oSettings, oData) {
         oData.oSearch.sSearch = "";
       }
     } );
   } );

 
   // Disallow state loading by returning false
   $(document).ready( function() {
     $('#example').dataTable( {
       "bStateSave": true,
       "fnStateLoadParams": function (oSettings, oData) {
         return false;
       }
     } );
   } );
fnStateLoaded
Show details

Callback that is called when the state has been loaded from the state saving method and the DataTables settings object has been modified as a result of the loaded state.
Default:
Type: function
Code example: 
   // Show an alert with the filtering value that was saved
   $(document).ready( function() {
     $('#example').dataTable( {
       "bStateSave": true,
       "fnStateLoaded": function (oSettings, oData) {
         alert( 'Saved filter was: '+oData.oSearch.sSearch );
       }
     } );
   } );
fnStateSave
Show details

Save the table state. This function allows you to define where and how the state information for the table is stored - by default it will use a cookie, but you might want to use local storage (HTML5) or a server-side database.
Default:
Type: function
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "bStateSave": true,
       "fnStateSave": function (oSettings, oData) {
         // Send an Ajax request to the server with the state object
         $.ajax( {
           "url": "/state_save",
           "data": oData,
           "dataType": "json",
           "method": "POST",
           "success": function () {}
         } );
       }
     } );
   } );
fnStateSaveParams
Show details

Callback which allows modification of the state to be saved. Called when the table has changed state a new state save is required. This method allows modification of the state saving object prior to actually doing the save, including addition or other state properties or modification. Note that for plug-in authors, you should use the 'stateSaveParams' event to save parameters for a plug-in.
Default:
Type: function
Code example: 
   // Remove a saved filter, so filtering is never saved
   $(document).ready( function() {
     $('#example').dataTable( {
       "bStateSave": true,
       "fnStateSaveParams": function (oSettings, oData) {
         oData.oSearch.sSearch = "";
       }
     } );
   } );