DataTables logo DataTables

This site contains the legacy documentation for DataTables v1.9 and earlier for reference only.
DataTables 1.10 is the current release and is now available.

Introduction

DataTables operates on the principle of progressive enhancement, whereby an enhanced and interactive table will be presented to the end user if their browser has the required capabilities. When you initialise the jQuery.dataTable object, information about the table is read directly from the HTML page. In combination with the default values for the features in DataTables, this makes it very easy to integrate directly into your web-site or web-application. Optionally, you can use the initialisation parameters to load data from locations other than the DOM, such as a server-side processing script or an Ajax obtained JSON file.

Prerequisites

In order for DataTables to be able to function correctly, the HTML for the target table must be laid out in a well formed manner with the 'thead' and 'tbody' sections declared. For example:

Column 1 Column 2 etc
Row 1 Data 1 Row 1 Data 2 etc
Row 2 Data 1 Row 2 Data 2 etc

Defining the 'tfoot' section is optional from the view point of DataTables, and if defined will be used in a similar manner to how thead is used, with the exception of not being able to use it to sort data.

Data sources

DataTables can take the data that it is to display from a number of different sources. This means that you are not limited to giving DataTables what it needs in one specific way, providing a great deal of flexibility. There are four core methods of giving data to DataTables:

DOM - At the basic level, you can give DataTables a reference to a table which already exists in your HTML page and it will enhance it for you. DataTables will read all of the information about the table from the page (the DOM) and add features such as filtering, paging and sorting. This follows the basis for progressive enhancement where a table will be enhanced if JavaScript is available, and not if the browser doesn't have the required capabilities.

JavaScript array - This provides the ability to give DataTables the information that you wish to display in the table as a JavaScript 2D array (i.e. an array of arrays). This is useful when your data is computed by JavaScript, or when adding a table to a page dynamically. It can also be used along side progressive enhancement to present the full table when JavaScript is enabled, but the HTML table would only show the first "page".

Ajax source - When the data you wish to display is available from a server and is not yet in the browser, you can ask DataTables to go to the server and pull the data back from it for display. A common use case for this is when you are displaying live information which could be periodically updated. Although the basic format that DataTables requires is fixed (an object with a 2D array called "aaData") you can use fnServerData to customise the Ajax call that DataTables makes, and also post-process data from one format to that which DataTables expects.

Server-side processing - When dealing with large data sets (for example 20 million rows) the web-browser simply can't cope with the amount of processing that is required for DataTables. Instead it's a good idea to pass off the data crunching to a process specifically designed for that - namely an SQL database (or any other data source!). The server-side process will do all of the pagination, sorting, filtering etc, while DataTables will simply display the results and handle user interaction.