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.

Sorting

Allowing your end user to sort data in your table is fundamental to a dynamically enhanced table on the web, making it easier for the user to access and understand the data that you are presenting. DataTables presents two APIs to allow further development and customisation of the sorting methods available:

To understand why both of these methods are presented, it is necessary to understand how sorting occurs in DataTables. When the data is read in form the original table (or from any other data source) DataTables will cache this data in order to optimise sorting, filtering and other functions it provides. This is perfect for the type based sorting method where you have a static string and want to sort the information in it, which is where the first API is applied. Plug-ins for this API will take the data string and (possibly) extract certain information from it before applying the sort. This method would be considered the 'primary' sorting method as it defined the actual sorting functions.

The second sorting type is required when the information in your table is not static - for example if there are user editable form elements. In this case the information must be read directly from the DOM and update the internally cached information in the DataTables instance. An example is a good way to illustrate this in action.

It is worth noting that the two APIs can be used together (i.e. the actions they take are mutually exclusive), so you can perform custom data source sorting to update the cached information and then have it sorted using a plug-in sorting function.

Type based column sorting

Sorting in DataTables is based on the detected type of the data column (you can add your own type detection functions, or override automatic detection using sType). With this specific type given to the column, DataTables will apply the required sorting function.

To add a new sort function to DataTables you need to attach your function to the object $.fn.dataTableExt.oSort. For example, the following adds a case sensitive sorting function of type 'string-case':

jQuery.fn.dataTableExt.oSort['string-case-asc']  = function(x,y) {
	return ((x < y) ? -1 : ((x > y) ?  1 : 0));
};

jQuery.fn.dataTableExt.oSort['string-case-desc'] = function(x,y) {
	return ((x < y) ?  1 : ((x > y) ? -1 : 0));
};

For each sort method you want to add, you need to add both an ascending method and a descending method. Each function should take two inputs, as you would expect from a Javascript sort function.

Note that the built-in sorting for the data types 'date', 'numeric' and 'string' are defined using this plug-in method. As such you may replace them if you wish to overrule DataTables' default processing to match what you specifically want.

Custom data source sorting

The plug-in functions described above work purely on static information and tie into the [].sort() method built into JavaScript. However, it can be desirable to update the information stored in DataTables when the information in the table is dynamic (for example form input elements which would not have the stings in the DataTables cache updated when the value is altered). To address this issue, DataTables provides an API which will use a custom defined function to update the cached information.

$.fn.dataTableExt.afnSortData

Function input parameters:

  1. object - DataTables settings object
  2. int - Column index (index in the data arrays)
  3. int - Column index (index for columns visible in the DOM - will be different to the second parameter if using hidden columns only)

Function return:

  1. array - the information that this column should be updated with. The length MUST match the length of aoData (after any 'null's have been removed).

The following example shows how you can update the cached sorting information with user entered values in HTML input elments. You can see this example in action on DOM sorting example page.

jQuery.fn.dataTableExt.afnSortData['dom-text'] = function  ( oSettings, iColumn )
{
	var aData = [];
	$( 'td:eq('+iColumn+') input', oSettings.oApi._fnGetTrNodes(oSettings) ).each( function () {
		aData.push( this.value );
	} );
	return aData;
}