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 additional files 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="myTable" 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 plain HTML. For more information about the different data sources DataTables can use, please see the data sources section of this manual.

Please also note that while DataTables supports colspan and rowspan in the table's header and footer, they are not supported in the table's tbody and must not be present.

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:

• Using the DataTables CDN
• Locally
• With a package manager such as NPM or Bower.

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" href="https://cdn.datatables.net/2.0.7/css/dataTables.dataTables.css" />
 
<script src="https://cdn.datatables.net/2.0.7/js/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" href="/DataTables/datatables.css" />

<script src="/DataTables/datatables.js"></script>

Node.js / 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 with its default styling:

npm install datatables.net-dt

ES modules

There are different ways of loading Javascript. The two most common ones used in Node.js and server-side bundlers are ES modules and CommonJS. The Javascript world is moving towards the newer ES module syntax, and the NPM DataTables package, plus all of its extensions, can operate with ES modules natively.

First install the packages you need, per the instructions above, then import the module:

import DataTable from 'datatables.net-dt';

let table = new DataTable('#myTable', {
    // config options...
});

To install and use extensions, you simply import them and they will automatically register against DataTables. For example to use Responsive:

import DataTable from 'datatables.net-dt';
import 'datatables.net-responsive-dt';

let table = new DataTable('#myTable', {
    responsive: true
});

Note that as of DataTables 1.13.4, you can use the import syntax to include DataTables in a project that down-compiles to CommonJS in exactly the same way as you would for ES modules. This is often the case in TypeScript projects.

CommonJS

CommonJS is an older loader type and is very common in the Node.js world (although now gradually being replaced by ES modules). DataTables packages all operate with CommonJS - e.g.:

var DataTable = require( 'datatables.net' );

let table = new DataTable('#myTable', {
    // config options...
});

Extensions are similar - note that you do not need to assign the require return to a variable. The functionality is automatically added to DataTables:

var DataTable = require( 'datatables.net' );
require( 'datatables.net-responsive' );

let table = new DataTable('#myTable', {
    responsive: true
});

Window-less environments

If you are building an application which provides its own window and document (i.e. not a web-browser), the CommonJS returned function's signature is slightly different - the packages export a factory function that can be executed with two optional arguments - the window and jQuery objects to use:

var $ = require( 'jquery' );
var DataTable = require( 'datatables.net' )(window, $);

let table = new DataTable('#myTable', {
    // config options...
});

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 () {
    $('#myTable').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.

Non-jQuery initialisation

If you prefer writing Javascript without using the abstractions jQuery provides, you can initialise DataTables (as of v1.11) using:

let table = new DataTable('#myTable', {
    // options
});

Where the parameters for new DataTable() are:

• A DOMString selector or HTML elements to pick the table(s) from the DOM.
• An object of DataTables options.

And the constructor will return a DataTables API instance allowing manipulation of the table.

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:

• Customise the DataTables options to suit your needs.
• Use the API to access and control the table programmatically.
• Style the table to match the theme of your web-site.
• Explore the DataTables examples.
• Take part in the DataTables community. Ask questions, answer others, make suggestions or simply say "Hi"!