DataTables logo
≡

Usage

Once you have DataTables installed and available on your page or in your app, it's time to actually use it and have DataTables work its magic on your tables!

Initialising DataTables

Intialistion of DataTables is done with the DataTable constructor, which accepts two parameters:

  1. A DOMString selector that will pick the table(s) you want to enhance from the document (you can also pass in an already selected element here if you prefer).
  2. Optionally, an object with configuration options (see below).
const table = new DataTable('#myTable');

This will create a new DataTable from the HTML element found with the id of myTable (change to suit your page of course) and assign the result, which is a DataTables API instance to the variable table. The variable assignment is optional, and only required if you are going to work with the API to programmatically control the table.

If you are running DataTables directly on a web-page, i.e. without using a framework or some other bundler, you may need to wait for the document to be fully loaded on the page. This can be done with the browser standard DOMContentLoaded event:

document.addEventListener('DOMContentLoaded', function() {
    let table = new DataTable('#myTable');
});

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. Read on to see how to customise DataTables to suit your needs.

Setting options

Configuration of DataTables is done by passing the options you want defined into the DataTables constructor as an object in the second parameter. For example:

new DataTable('#myTable', {
    paging: false
});

This uses the paging option to disable paging for the table.

Let's say you want to enable scrolling in the table - you would use the scrollY option:

new DataTable('#myTable', {
    scrollY: 400
});

Extending that, you can combine multiple options into a single object. In this case we enable scrolling and disable paging:

new DataTable('#myTable', {
    paging: false,
    scrollY: 400
});

The object being passed in is just a standard Javascript object and can be treated as such. Add as many options as you wish! You can also define the object as a variable and then manipulate it using logic to change options as needed (e.g. for different user permissions).

For the full range of configuration options available for DataTables, please refer to the options reference section of this web-site.

HTML 5 data attributes

As of v1.10.5 DataTables can also use initialisation options read from HTML5 data-* attributes. This provides a mechanism for setting options directly in your HTML, rather than using Javascript (as above). Consider for example the following table:

<table data-order='[[ 1, "asc" ]]' data-page-length='25'>
    <thead>
        <tr>
            <th>Name</th>
            <th>Position</th>
            <th>Office</th>
            <th>Age</th>
            <th>Start date</th>
            <th data-class-name="priority">Salary</th>
        </tr>
    </thead>
</table>

When DataTables is initialised on this table it will set pageLength to 25, order by the second column automatically (order) and set a class name on the final column of the table (columns.className).

There are two important points to consider when using data-* attributes as initialisation options:

  • Dashed strings in attribute names will be automatically converted to the camel case notation used by DataTables (e.g. use data-page-length for pageLength).
  • If using a string inside the attribute it must be in double quotes (and therefore the attribute as a whole in single quotes).

Common options

Some of the options you might find particularly useful are:

Setting defaults

When on projects that use multiple DataTables it is often useful to set the initialisation defaults to common values (for example you might want to set the dom option to a common value so all tables get the same layout). This can be done using the DataTable.defaults object. This object takes all of the same parameters as the DataTables initialisation object, but in this case you are setting the default for all future initialisations of DataTables.

In this example we disable the searching and ordering features of DataTables by default, but when the table is initialised, it is initialised with ordering enabled (overriding the default).

// Disable search and ordering by default
DataTable.defaults.searching = false;
DataTable.defaults.ordering = false;

// For this specific table we are going to enable ordering
// (searching is still disabled)
new DataTable('#myTable', {
    ordering: true
});

Extensions

Many of DataTables extensions can also be configured through the DataTables configuration object, initialising the extension and configuring it as required. The properties available depend upon the extensions used, and the extension Javascript must be loaded in order for those options to operate.

For example, consider the Select extension which provides the end user with the ability to dynamically select rows, columns and cells in the table. It presents the select option which can be set to true to enable selection:

new DataTable('#myTable', {
    select: true
});

The select option can also be given as an object to give fine grained control over the selection options and of course can be combined with the other DataTables options.

The options reference provides a searchable list of all options from DataTables and the extensions.

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: