DataTables logo DataTables

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.

fnAddData
Show details 		Add a single new row or multiple rows of data to the table.
Input parameters:
  1. array strings : The data to be added to the table. This array must be of the same length as the number of columns on the original HTML table.
    or
    array array strings : 2D array of data to be added to the table. The inner array must be of the same length as the number of columns on the original HTML table.
  2. boolean : optional - redraw the table or not after adding the new data (default true)
Return parameter: array indexes: the list of indexes in aoData (internal parameters, use fnSettings() to obtain) that have been added to the table.
Code example: 
var oTable;

/* Global var for counter */
var giCount = 2;

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

function fnClickAddRow() {
	oTable.fnAddData( [
		giCount+".1",
		giCount+".2",
		giCount+".3",
		giCount+".4" ] );
	
	giCount++;
}
fnClearTable
Show details 		Empty the entire table of current row information.
Input parameters:
  1. boolean (optional) : Redraw the table or not. Default true.
Return parameter: void
Code example: 
var oTable;

$(document).ready(function() {
	oTable = $('#example').dataTable();
	
	/* Immediatly '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:
  1. node : The TR element to 'close'
Return parameter: void
Code example: 
var oTable;

$(document).ready(function() {
	/* 'open' an information row when a row is clicked on */
	$('#example tbody tr').click( function () {
		var that = this;
		oTable.fnOpen( this, "Temporary row opened", "info_row" );
		
		/* Then when the info row is clicked upon - close it */
		$('#example .info_row').click( function () {
			oTable.fnClose(that);
		} );
	} );
	
	oTable = $('#example').dataTable();
} );
fnDeleteRow
Show details 		Remove a row from the table. Redraw is automatic on this function.
Input parameters:
  1. node (TR): the TR element that should be deleted from the table
    or
    int : Index of the row to delete from the aoData object (use the fnGetPosition() API function to find the index of a row in this array).
  2. function (optional) : Callback function for when the row has been deleted
  3. boolean (optional) : Null the row from the internal aoData object (useful if you are using fnGetNodes()) or not. Default false.
Return parameter: void
Code example: 
var oTable;

$(document).ready(function() {
	oTable = $('#example').dataTable();
	
	/* Immediately remove the first row. You wouldn't want to do it this way... */
	oTable.fnDeleteRow( 0 );
} );
fnDraw
Show details 		Redraw the table.
Input parameters:
  1. bool (optional): indicate if the redraw should be complete (i.e. re-sort and re-filter), which has the side effect of resetting the pagination, or just update the display as it is. Default - true
Return parameter: void
Code example: 
var oTable;

$(document).ready(function() {
	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 table based on the string input. This will automatically redraw the table. This can also be used to filter upon an individual column, and/or to allow regular expression characters to be parsed (good for OR/AND statements).
Input parameters:
  1. string : String to filter on.
  2. int (optional): Column to limit filtering to - default null. Note that the column counting index starts at zero.
  3. bool (optional) : Escape regular special characters or not - default true.
Return parameter: void
Code example: 
var oTable;

$(document).ready(function() {
	oTable = $('#example').dataTable();
	
	/* Filter immediately */
	oTable.fnFilter( 'test string' );
} );
fnGetData
Show details 		Get the data array which DataTables uses to make up the table. Best used in combination with fnGetPosition().
Input parameters:
  1. node (TR): The TR element for which to get the data array for
    or
    int : The index of the row to get. If supplied the function will return that row array alone
    or
    void: if no argument is passed, DataTables will return a 2D array of the entire table.
Return parameter: array string or array array string: (dependent on the input parameter).
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( this );
		
		/* Update the data array and return the value */
		aData[ aPos[1] ] = 'clicked';
		this.innerHTML = 'clicked';
	} );
	
	/* Init DataTables */
	oTable = $('#example').dataTable();
} );
fnGetNodes
Show details 		Get a single TR node or all TR nodes for the table. Useful for event manipulation.
Input parameters:
  1. int (optional) : The index of the node row to get. If supplied the function will return that node alone. If not supplied the function will return the node list for the whole table. Note that this index is not the visible index, but rather the internal cache index that DataTables maintains.
Return parameter: array nodes or node (dependent on the input parameter) : an array of all TR nodes that might be used in the table or the single target node.
Code example: 
var oTable;

$(document).ready(function() {
	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. Best used in combination with fnGetData().
Input parameters:
  1. nNode : the node you want to find the position of. This my be either a 'TR' row or a 'TD' cell from the table. The return parameter depends on this input.
Return parameter: int or array [ int, int, int ] : if the node is a table row (TR) then the return value will be an integer with the index of the row in the aoData object. If the node is a table cell (TD) then the return value will be an array with [ aoData index row, column index (discounting hidden rows),column index (including hidden rows) ].
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();
} );
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:
  1. node - the table row to 'open'
  2. string - the HTML to put into the row
  3. string - class to give the TD element that is created
Return parameter: node: - TR node that was created for the 'opened' row.
Code example: 
var oTable;

$(document).ready(function() {
	/* 'open' an information row when a row is clicked on */
	$('#example tbody tr').click( function () {
		var that = this;
		oTable.fnOpen( this, "Temporary row opened", "info_row" );
		
		/* Then when the info row is clicked upon - close it */
		$('#example .info_row').click( function () {
			oTable.fnClose(that);
		} );
	} );
	
	oTable = $('#example').dataTable();
} );
fnPageChange
Show details 		Provide the internal logic for pagination in a simple API function. With this function to can have a DataTables table go to the next, previous, first or last pages.
Input parameters:
  1. string : The paging action to take. This value may be "next", "previous", "first" or "last" - note that this string is case sensitive.
  2. bool (optional) : Redraw the table after inserting the table (optional - default true)
Return parameter: void
Code example: 
$(document).ready(function() {
	oTable = $('#example').dataTable();
	oTable.fnPageChange( 'next' );
} );
fnSetColumnVis
Show details 		Set the visibility of a given column on-the-fly. Please note that this function does not support 'complex headers' (colspan and rowspan on columns).
Input parameters:
  1. int : Column to change the visibility of.
  2. boolean : Set column to visible (true) or hidden (false)
Return parameter: void
Code example: 
var oTable;

$(document).ready(function() {
	oTable = $('#example').dataTable();
	
	/* Hide the second column after initialisation*/
	oTable.fnSetColumnVis( 1, false );
} );
fnSettings
Show details 		Access the internal DataTables parameters for a table.
Input parameters: void
Return parameter: Settings object
Code example: 
var oTable;

$(document).ready(function() {
	oTable = $('#example').dataTable();
	var oSettings = oTable.fnSettings();
	
	/* Show an example parameter from the settings */
	alert( oSettings._iDisplayStart );
} );
fnSort
Show details 		Sort the table - allows for single or multi-column sorting to be triggered by a Javascript function call.
Input parameters:
  1. array array [int, string] : Multi-column sorting array.
Return parameter: void
Code example: 
var oTable;

$(document).ready(function() {
	oTable = $('#example').dataTable();
	
	/* Sort immediately with columns 0 and 1 */
	oTable.fnSort( [ [0,'asc'], [1,'asc'] ] );
} );
fnSortListener
Show details 		Add a sort listener to an element. This is basically the same function that DataTables uses when it added the listeners to the TH elements for click to sort. This allows external elements to control sorting, with out you needing to worry about any of the external logic.
Input parameters:
  1. node: the element to attach the sort listener to.
  2. int: the column that a click on this node will sort on.
  3. function: callback function when sort is run - optional
Return parameter: void
Code example: 
var oTable;

$(document).ready(function() {
	oTable = $('#example').dataTable();
	
	/* Sort on column 1, when 'sorter' is clicked on */
	oTable.fnSortListener( document.getElementById('sorter'), 1 );
} );
fnUpdate
Show details 		Update the table with new data, taking account of sorting, filtering and any other features that DataTables provides. This function can update either a single cell (the first parameter needs to be a string), or a whole row (the first parameter is an array of strings).
Input parameters:
  1. string : The data to be added to the table. This array must be of the same length as the number of columns on the original HTML table.
    or
    array strings : Data to update the row with
  2. int : Row to update (based upon aoData - use fnGetPosition())
    or
    node (TR): The TR element that the update should target
  3. int : Column number to update - including hidden columns (ignored if the first parameter is an array)
  4. bool (optional) : Redraw the table after inserting the table (optional - default true)
Return parameter: int : 0 okay, 1 error
Code example: 
var oTable;

$(document).ready(function() {
	oTable = $('#example').dataTable();
	oTable.fnUpdate( 'Example update', 0, 0 ); /* Single cell */
	oTable.fnUpdate( ['a', 'b', 'c', 'd', 'e'], 1, 0 );	/* 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:
  1. 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 (DataTables is greater or equal to the version checked), or false (DataTables is of an older version to that checked).
Code example: 
var oTable;

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