Installation

DataTables is a powerful Javascript library for adding interaction features to HTML tables, and while simplicity is a core design principle for the project as a whole, it can appear quite daunting to get started. However, taking those first steps and getting DataTables running on your web-site is actually quite straight forward as you need only include two files additional in your page:

  • The DataTables Javascript file
  • The DataTables CSS file

There are other files available such as Editor for adding editing abilities, and other plug-ins, which can be used to extend the feature set of DataTables, but basically, all you need to do is include these two files to get up and running!

Requirements

Before we get started, we need to consider the requirements DataTables has in order to operate.

Dependencies

DataTables has only one library dependency (other software upon which it relies in order to work) - jQuery. Being a jQuery plug-in, DataTables makes use of many of the excellent features that jQuery provides, and hooks into the jQuery plug-in system, in the same way as all other jQuery plug-ins. jQuery 1.7 or newer will work with DataTables, although typically you will want to use the latest version. DataTables includes everything else that it requires to operate.

HTML

For DataTables to be able to enhance an HTML table, the table must be valid, well formatted HTML, with a header (thead) and a single body (tbody). An optional footer (tfoot) can also be used.

<table id="table_id" class="display">
    <thead>
        <tr>
            <th>Column 1</th>
            <th>Column 2</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Row 1 Data 1</td>
            <td>Row 1 Data 2</td>
        </tr>
        <tr>
            <td>Row 2 Data 1</td>
            <td>Row 2 Data 2</td>
        </tr>
    </tbody>
</table>

If you are generating your HTML document using a server-side program, such as a PHP script, a Ruby script, a C# program or anything else - all they need to do is output your table like this. This is exactly what you would have for a normal HTML table, although sometimes you might need to add the thead and tbody tags, as these aren't always used (they allow DataTables to know what should be used for the column headers and the click-to-order controls).

Note that DataTables can actually generate the thead and tbody for you, along with all of the rows and cells of the table, if you are using Ajax sourced data, but for the moment we'll focus on a plain HTML. For more information about the different data sources DataTables can use, please see the data sources section of this manual.

Installing Javascript / CSS

The key part of the installation of DataTables is including the DataTables source files on your page. As noted at the top of this page, this simply involves including the DataTables Javascript and CSS files. The CSS file is actually optional, but it provides default styling for your table to make it look good with minimum effort. See the style theme creator if you want to customise the colours of the default DataTables CSS.

The required files can be installed in a number of different ways:

CDN

A CDN is a Content Delivery Network which has edge servers that are tuned to provide media files with very low latency to web-browsers, and as a user receives a file from the CDN the browser will cache it for reuse. This means that different sites using the same Javascript library can share a large performance improvement since the browser does not need to download the same file from different servers for each site.

The DataTables CDN is powered by CloudFlare which has edge servers all around the world, ensuring that the Javascript and CSS for DataTables can be loaded as quickly as possible by your visitor's browsers.

To include DataTables on your page simply include the following HTML (remember to include jQuery as well:

<link rel="stylesheet" type="text/css" href="//cdn.datatables.net/1.10.16/css/jquery.dataTables.css">
 
<script type="text/javascript" charset="utf8" src="//cdn.datatables.net/1.10.16/js/jquery.dataTables.js"></script>

Local installation

If you prefer not to use a CDN, and instead have the files hosted on your own server, or if you want to modify the files at all, it is just as simple to get going with DataTables.

Simply use the download builder to download the latest version of DataTables, select any additionally software and styling you want and download the customised package. Then unzip and upload to your web-server. You will then have a directory called DataTables available on your server. Then include DataTables on your page using the following HTML:

<link rel="stylesheet" type="text/css" href="/DataTables/datatables.css">

<script type="text/javascript" charset="utf8" src="/DataTables/datatables.js"></script>

NPM

DataTables and its extensions are available as NPM packages. The package base name is datatables.net and the extensions and styling integration options are available as individual packages - see the NPM install guide for full details on the available packages.

For example the following can be used to install DataTables and its default styling:

npm install datatables.net    # Core library
npm install datatables.net-dt # Styling

The DataTables packages all export a factory function that can be executed with two optional arguments - the window and jQuery object to use - again see the NPM install guide for details on these parameters. When using Browserify you can simply execute the function without any parameters - e.g.:

var $  = require( 'jquery' );
var dt = require( 'datatables.net' )();

Bower

DataTables, its extensions and styling options are also available as Bower packages. The package names are identical to the NPM packages with datatables.net as the base name. To install DataTables and its default styling via bower use:

bower install --save datatables.net
bower install --save datatables.net-dt

Initialising DataTables

That's almost it! We've got the HTML table we want to enhance, and we've got all the software and styles we need. All that is now required is to tell DataTables to actually work its magic on the table. This is done with a few lines of Javascript:

$(document).ready( function () {
    $('#table_id').DataTable();
} );

If you've used jQuery before, you will recognise the form of this script: we wait for the document to be fully ready, and then select the table we want, and run the DataTables function on it.

That's it! DataTables will add ordering, searching, paging and information to your table by default, giving your end users the ability to find the information they want as quickly as possible.

If you want to customise your DataTable, this can be done by specifying configuration parameters in an object passed to the DataTable() function. For information on how to use these configuration parameter, please refer to the options manual page.

Next steps

With the basics of how to get DataTables going under your belt, you might now want to explore some of the other options to enhance your tables further: