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.

Javascript API

Although most of the time your Javascript interaction with DataTables will be done using the initialisation object as described in the Usage section of this site, there are times at which you might find it useful to have some external control of the table. The following functions are available from the jQuery.dataTable object.

There are also a number of plug-in API functions available which extend the capabilities of DataTables beyond the built-in functions described on this page.

Note for those using server-side processing: A number of the API functions make the assumption that data storage it done on the client-side, rather than the server-side. As such functions such as fnAddData and fnDeleteRow will not effect the data held on your database. Indeed DataTables does not know if you are even using a database! As such, you must make the required calls to the server to manipulate your data as required, and then simply redraw the table (fnDraw) to view the new data.

$
Show details

Perform a jQuery selector action on the table's TR elements (from the tbody) and return the resulting jQuery object.

Input parameters:

{string|node|jQuery}: jQuery selector or node collection to act on
{object}: Optional parameters for modifying the rows to be included
{string} [default=none]: Select TR elements that meet the current filter criterion ("applied") or all TR elements (i.e. no filter).
{string} [default=current]: Order of the TR elements in the processed array. Can be either 'current', whereby the current sorting of the table is used, or 'original' whereby the original order the data was read into the table is used.
{string} [default=all]: Limit the selection to the currently displayed page ("current") or not ("all"). If 'current' is given, then order is assumed to be 'current' and filter is 'applied', regardless of what they might be given as.

Return parameter: {object}: jQuery object, filtered by the given selector.

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
 
  // Highlight every second row
  oTable.$('tr:odd').css('backgroundColor', 'blue');
} );
 
 
$(document).ready(function() {
  var oTable = $('#example').dataTable();
 
  // Filter to rows with 'Webkit' in them, add a background colour and then
  // remove the filter, thus highlighting the 'Webkit' rows only.
  oTable.fnFilter('Webkit');
  oTable.$('tr', {"filter": "applied"}).css('backgroundColor', 'blue');
  oTable.fnFilter('');
} );

_
Show details

Almost identical to $ in operation, but in this case returns the data for the matched rows - as such, the jQuery selector used should match TR row nodes or TD/TH cell nodes rather than any descendants, so the data can be obtained for the row/cell. If matching rows are found, the data returned is the original data array/object that was used to create the row (or a generated array if from a DOM source).

This method is often useful in-combination with $ where both functions are given the same parameters and the array indexes will match identically.

Input parameters:

{string|node|jQuery}: jQuery selector or node collection to act on
{object}: Optional parameters for modifying the rows to be included
{string} [default=none]: Select elements that meet the current filter criterion ("applied") or all elements (i.e. no filter).
{string} [default=current]: Order of the data in the processed array. Can be either 'current', whereby the current sorting of the table is used, or 'original' whereby the original order the data was read into the table is used.
{string} [default=all]: Limit the selection to the currently displayed page ("current") or not ("all"). If 'current' is given, then order is assumed to be 'current' and filter is 'applied', regardless of what they might be given as.

Return parameter: {array}: Data for the matched elements. If any elements, as a result of the selector, were not TR, TD or TH elements in the DataTable, they will have a null entry in the array.

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
 
  // Get the data from the first row in the table
  var data = oTable._('tr:first');
 
  // Do something useful with the data
  alert( "First cell is: "+data[0] );
} );
 
 
$(document).ready(function() {
  var oTable = $('#example').dataTable();
 
  // Filter to 'Webkit' and get all data for 
  oTable.fnFilter('Webkit');
  var data = oTable._('tr', {"filter": "applied"});
   
  // Do something with the data
  alert( data.length+" rows matched the filter" );
} );

fnAddData
Show details

Add a single new row or multiple rows of data to the table. Please note that this is suitable for client-side processing only - if you are using server-side processing (i.e. "bServerSide": true), then to add data, you must add it to the data source, i.e. the server-side, through an Ajax call.

Input parameters:

{array|object}: The data to be added to the table. This can be:
- 1D array of data - add a single row with the data provided
- 2D array of arrays - add multiple rows in a single call
- object - data object when using mData
- array of objects - multiple data objects when using mData
{bool} [default=true]: redraw the table or not

Return parameter: {array}: An array of integers, representing the list of indexes in aoData ({@link DataTable.models.oSettings}) that have been added to the table.

Code example:

// Global var for counter
var giCount = 2;
 
$(document).ready(function() {
  $('#example').dataTable();
} );
 
function fnClickAddRow() {
  $('#example').dataTable().fnAddData( [
    giCount+".1",
    giCount+".2",
    giCount+".3",
    giCount+".4" ]
  );
     
  giCount++;
}

fnAdjustColumnSizing
Show details

This function will make DataTables recalculate the column sizes, based on the data contained in the table and the sizes applied to the columns (in the DOM, CSS or through the sWidth parameter). This can be useful when the width of the table's parent element changes (for example a window resize).

Input parameters:

{boolean} [default=true]: Redraw the table or not, you will typically want to

Return parameter:

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable( {
    "sScrollY": "200px",
    "bPaginate": false
  } );
   
  $(window).bind('resize', function () {
    oTable.fnAdjustColumnSizing();
  } );
} );

fnClearTable
Show details

Quickly and simply clear a table

Input parameters:

{bool} [default=true]: redraw the table or not

Return parameter:

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
   
  // Immediately 'nuke' the current rows (perhaps waiting for an Ajax callback...)
  oTable.fnClearTable();
} );

fnClose
Show details

The exact opposite of 'opening' a row, this function will close any rows which are currently 'open'.

Input parameters:

{node}: the table row to 'close'

Return parameter: {int}: 0 on success, or 1 if failed (can't find the row)

Code example:

$(document).ready(function() {
  var oTable;
   
  // 'open' an information row when a row is clicked on
  $('#example tbody tr').click( function () {
    if ( oTable.fnIsOpen(this) ) {
      oTable.fnClose( this );
    } else {
      oTable.fnOpen( this, "Temporary row opened", "info_row" );
    }
  } );
   
  oTable = $('#example').dataTable();
} );

fnDeleteRow
Show details

Remove a row for the table

Input parameters:

{mixed}: The index of the row from aoData to be deleted, or the TR element you want to delete
{function|null}: Callback function
{bool} [default=true]: Redraw the table or not

Return parameter: {array}: The row that was deleted

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
   
  // Immediately remove the first row
  oTable.fnDeleteRow( 0 );
} );

fnDestroy
Show details

Restore the table to it's original state in the DOM by removing all of DataTables enhancements, alterations to the DOM structure of the table and event listeners.

Input parameters:

{boolean} [default=false]: Completely remove the table from the DOM

Return parameter:

Code example:

$(document).ready(function() {
  // This example is fairly pointless in reality, but shows how fnDestroy can be used
  var oTable = $('#example').dataTable();
  oTable.fnDestroy();
} );

fnDraw
Show details

Redraw the table

Input parameters:

{bool} [default=true]: Re-filter and resort (if enabled) the table before the draw.

Return parameter:

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
   
  // Re-draw the table - you wouldn't want to do it here, but it's an example :-)
  oTable.fnDraw();
} );

fnFilter
Show details

Filter the input based on data

Input parameters:

{string}: String to filter the table on
{int|null}: Column to limit filtering to
{bool} [default=false]: Treat as regular expression or not
{bool} [default=true]: Perform smart filtering or not
{bool} [default=true]: Show the input global filter in it's input box(es) - please note that this option will not operate with DataTables 1.10+ as it has been removed from the latest versions.
{bool} [default=true]: Do case-insensitive matching (true) or not (false)

Return parameter:

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
   
  // Sometime later - filter...
  oTable.fnFilter( 'test string' );
} );

fnGetData
Show details

Get the data for the whole table, an individual row or an individual cell based on the provided parameters.

Input parameters:

{int|node}: A TR row node, TD/TH cell node or an integer. If given as a TR node then the data source for the whole row will be returned. If given as a TD/TH cell node then iCol will be automatically calculated and the data for the cell returned. If given as an integer, then this is treated as the aoData internal data index for the row (see fnGetPosition) and the data for that row used.
{int}: Optional column index that you want the data of.

Return parameter: {array|object|string}: If mRow is undefined, then the data for all rows is returned. If mRow is defined, just data for that row, and is iCol is defined, only data for the designated cell is returned.

Code example:

// Row data
$(document).ready(function() {
  oTable = $('#example').dataTable();
 
  oTable.$('tr').click( function () {
    var data = oTable.fnGetData( this );
    // ... do something with the array / object of data for the row
  } );
} );
 
 
// Individual cell data
$(document).ready(function() {
  oTable = $('#example').dataTable();
 
  oTable.$('td').click( function () {
    var sData = oTable.fnGetData( this );
    alert( 'The cell clicked on had the value of '+sData );
  } );
} );

fnGetNodes
Show details

Get an array of the TR nodes that are used in the table's body. Note that you will typically want to use the '$' API method in preference to this as it is more flexible.

Input parameters:

{int}: Optional row index for the TR element you want

Return parameter: {array|node}: If iRow is undefined, returns an array of all TR elements in the table's body, or iRow is defined, just the TR element requested.

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
   
  // Get the nodes from the table
  var nNodes = oTable.fnGetNodes( );
} );

fnGetPosition
Show details

Get the array indexes of a particular cell from it's DOM element and column index including hidden columns

Input parameters:

{node}: this can either be a TR, TD or TH in the table's body

Return parameter: {int}: If nNode is given as a TR, then a single index is returned, or if given as a cell, an array of [row index, column index (visible), column index (all)] is given.

Code example:

$(document).ready(function() {
  $('#example tbody td').click( function () {
    // Get the position of the current data from the node
    var aPos = oTable.fnGetPosition( this );
     
    // Get the data array for this row
    var aData = oTable.fnGetData( aPos[0] );
     
    // Update the data array and return the value
    aData[ aPos[1] ] = 'clicked';
    this.innerHTML = 'clicked';
  } );
   
  // Init DataTables
  oTable = $('#example').dataTable();
} );

fnIsOpen
Show details

Check to see if a row is 'open' or not.

Input parameters:

{node}: the table row to check

Return parameter: {boolean}: true if the row is currently open, false otherwise

Code example:

$(document).ready(function() {
  var oTable;
   
  // 'open' an information row when a row is clicked on
  $('#example tbody tr').click( function () {
    if ( oTable.fnIsOpen(this) ) {
      oTable.fnClose( this );
    } else {
      oTable.fnOpen( this, "Temporary row opened", "info_row" );
    }
  } );
   
  oTable = $('#example').dataTable();
} );

fnOpen
Show details

This function will place a new row directly after a row which is currently on display on the page, with the HTML contents that is passed into the function. This can be used, for example, to ask for confirmation that a particular record should be deleted.

Input parameters:

{node}: The table row to 'open'
{string|node|jQuery}: The HTML to put into the row
{string}: Class to give the new TD cell

Return parameter: {node}: The row opened. Note that if the table row passed in as the first parameter, is not found in the table, this method will silently return.

Code example:

$(document).ready(function() {
  var oTable;
   
  // 'open' an information row when a row is clicked on
  $('#example tbody tr').click( function () {
    if ( oTable.fnIsOpen(this) ) {
      oTable.fnClose( this );
    } else {
      oTable.fnOpen( this, "Temporary row opened", "info_row" );
    }
  } );
   
  oTable = $('#example').dataTable();
} );

fnPageChange
Show details

Change the pagination - provides the internal logic for pagination in a simple API function. With this function you can have a DataTables table go to the next, previous, first or last pages.

Input parameters:

{string|int}: Paging action to take: "first", "previous", "next" or "last" or page number to jump to (integer), note that page 0 is the first page.
{bool} [default=true]: Redraw the table or not

Return parameter:

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
  oTable.fnPageChange( 'next' );
} );

fnSetColumnVis
Show details

Show a particular column

Input parameters:

{int}: The column whose display should be changed
{bool}: Show (true) or hide (false) the column
{bool} [default=true]: Redraw the table or not

Return parameter:

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
   
  // Hide the second column after initialisation
  oTable.fnSetColumnVis( 1, false );
} );

fnSettings
Show details

Get the settings for a particular table for external manipulation

Input parameters:

Return parameter: {object}: DataTables settings object. See {@link DataTable.models.oSettings}

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
  var oSettings = oTable.fnSettings();
   
  // Show an example parameter from the settings
  alert( oSettings._iDisplayStart );
} );

fnSort
Show details

Sort the table by a particular column

Input parameters:

{int}: the data index to sort on. Note that this will not match the 'display index' if you have hidden data entries

Return parameter:

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
   
  // Sort immediately with columns 0 and 1
  oTable.fnSort( [ [0,'asc'], [1,'asc'] ] );
} );

fnSortListener
Show details

Attach a sort listener to an element for a given column

Input parameters:

{node}: the element to attach the sort listener to
{int}: the column that a click on this node will sort on
{function}: callback function when sort is run

Return parameter:

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
   
  // Sort on column 1, when 'sorter' is clicked on
  oTable.fnSortListener( document.getElementById('sorter'), 1 );
} );

fnUpdate
Show details

Update a table cell or row - this method will accept either a single value to update the cell with, an array of values with one element for each column or an object in the same format as the original data source. The function is self-referencing in order to make the multi column updates easier.

Input parameters:

{object|array|string}: Data to update the cell/row with
{node|int}: TR element you want to update or the aoData index
{int}: The column to update (set to undefined to update the whole row)
{bool} [default=true]: Redraw the table or not
{bool} [default=true]: Perform pre-draw actions or not

Return parameter: {int}: 0 on success, 1 on error

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
  oTable.fnUpdate( 'Example update', 0, 0 ); // Single cell
  oTable.fnUpdate( ['a', 'b', 'c', 'd', 'e'], 1 ); // Row
} );

fnVersionCheck
Show details

Provide a common method for plug-ins to check the version of DataTables being used, in order to ensure compatibility.

Input parameters:

{string}: Version string to check for, in the format "X.Y.Z". Note that the formats "X" and "X.Y" are also acceptable.

Return parameter: {boolean}: true if this version of DataTables is greater or equal to the required version, or false if this version of DataTales is not suitable

Code example:

$(document).ready(function() {
  var oTable = $('#example').dataTable();
  alert( oTable.fnVersionCheck( '1.9.0' ) );
} );

Static methods

As well as the functions above which apply to individual tables, DataTables provides a number of static functions which give general information about the use of DataTables on the page. These functions can be accessed through the object $.fn.dataTable.{functionName}.

fnVersionCheck
Show details

Provide a common method for plug-ins to check the version of DataTables being used, in order to ensure compatibility.

Input parameters:

{string}: Version string to check for, in the format "X.Y.Z". Note that the formats "X" and "X.Y" are also acceptable.

Return parameter: {boolean}: true if this version of DataTables is greater or equal to the required version, or false if this version of DataTales is not suitable

Code example:

1	`alert( $.fn.dataTable.fnVersionCheck(` `'1.9.0'` `) );`

fnIsDataTable
Show details

Check if a TABLE node is a DataTable table already or not.

Input parameters:

{node}: The TABLE node to check if it is a DataTable or not (note that other node types can be passed in, but will always return false).

Return parameter: {boolean}: true the table given is a DataTable, or false otherwise

Code example:

var ex = document.getElementById('example');
if ( ! $.fn.DataTable.fnIsDataTable( ex ) ) {
  $(ex).dataTable();
}

fnTables
Show details

Get all DataTable tables that have been initialised - optionally you can select to get only currently visible tables.

Input parameters:

{boolean} [default=false]: Flag to indicate if you want all (default) or visible tables only.

Return parameter: {array}: Array of TABLE nodes (not DataTable instances) which are DataTables

Code example:

var table = $.fn.dataTable.fnTables(true);
if ( table.length > 0 ) {
  $(table).dataTable().fnAdjustColumnSizing();
}

DataTables designed and created by SpryMedia © 2008-2014
DataTables is dual licensed under the GPL v2 license or a BSD (3-point) license.