DataTables logo
≡

Quick Start: CDN / Download

You've got an HTML page with a table that you want to add high-performance, high-impact interactive controls to? You are in the right place!

Script in 60 Seconds

This guide will give you a superfast introduction to installing and configuring DataTables on a plain HTML page. In 60 seconds, you'll have a DataTable on your web-page!

If you don't yet have a page that contains a table and want to follow along with this example, open this StackBlitz to get a very simple starter page that you can edit and see the effects of your changes immediately.

1. Install

First up is to include the DataTables JavaScript and CSS on your page in the head section of the HTML with these two tags:

<link rel="stylesheet" href="https://cdn.datatables.net/v/dt/dt-3.1.3/datatables.min.css">
<script src="https://cdn.datatables.net/v/dt/dt-3.1.3/datatables.min.js"></script>

You can always get the latest DataTables software from the download page. There you will be able to select the styling and extensions you want for your install (we'll come back to those options later)! You can also use the download page to download the DataTables CSS and JavaScript if you prefer it on your own server, rather than using the DataTables CDN.

2. Initialise

The next step is to tell DataTables to run on your table. You do this by using new DataTable(), passing in the first argument as the table you want to enhance and optionally a second argument for customisation. Let's get this table running - insert the following at the end of the body:

<script defer>
    new DataTable('#audiobooks');
</script>

As your page grows you will want to keep your initialisation code in separate files and possibly load them from the page head. In such a case you need to make sure that the HTML has fully loaded before initialising the DataTable. DataTables provides a utility method for this:

DataTable.Dom.s(document).on('ready', () => {
    new DataTable('#audiobooks');
});

Awesome - your table will now have instant filtering, ordering and paging controls!

3. Customise

We've got an interactive DataTable, but now, let's make it yours! DataTables has a huge range of customisation options, so let's make use of them. For our demo table we want to:

  1. Change the default ordering to be on the release date (ordering).
  2. Set the default page length to 25 (pageLength).
  3. Display the date in a locale-specific format for the end user using a renderer and columns.render.
  4. Format the price to be locale specific as well.

We do this by passing a configuration object as the second parameter to the DataTable constructor:

new DataTable('#audiobooks', {
    columnDefs: [
        { target: 2, render: DataTable.render.date() },
        { target: 3, render: DataTable.render.number(null, null, 2, '$') },
    ],
    order: [2, 'desc'],
    pageLength: 25,
});

Here columnDefs lets use apply column-specific options to particular columns.

Result!

The result is a simple HTML web-page with a comprehensive table library embedded into it:

Ajax

Keen for more? Excellent! Driving static HTML tables is straightforward, but at some point, perhaps immediately, you'll want to load data from an Ajax source rather than using static HTML. If your data is being stored in a database, this is typically the method you'll be using.

As above, I'll show you the principles of how to use Ajax here so you can build it into your own tables, but if you want to follow along here is a StackBlitz starter.

Data

In this example, we are going to load JSON data from a static file (in reality you will likely want to use a server-side script to read the data from a database - check out the server-side libraries for DataTables if you take that route). The data for this example will have this basic structure:

{
  "data": [
        {
            "id": 1,
            "title": "Designing Data-Intensive Applications",
            "author": "Martin Kleppmann",
            "releaseDate": "2017-03-16",
            "price": 29.99,
            "finished": true,
            "isFiction": false
        },
    ]
}

Note that the JSON contains a top-level data property - this is optional (you can use ajax.dataSrc to remove the need for that, or change the name), but it is useful as it allows other data to be returned from the server as well as the rows to show in the table.

The data array contains an object per row for the table.

HTML

Include DataTables' CSS and JavaScript in the head of your page, the same as in the example above - that stays just the same. However, the table will be different - you will no longer have data in it since we are going to populate it via Ajax.

We can even instruct DataTables to create the column titles using the columns.title option (this is optional, you can use a thead in the HTML if you prefer to define the columns there, and this can be useful for complex headers with colspan and rowspan attributes). As such, let's just have an empty table:

<table id="audiobooks" class="display"></table>

It is worth noting here that the display class is used to activate DataTables row striping, order highlighting and other styling features. DataTables has a number of styling options controlled by the class applied to the table - for example, you could add nowrap to the class list if you don't want the cell text to wrap.

Furthermore, this is just the default styling for DataTables. DataTables also has seamless integration with popular styling libraries such as Bootstrap and Bulma. Use the download builder to select the styling you want for your page.

Configuration

To have DataTables read data from an Ajax source we use the ajax option and set it to point at the address we'll load the data from.

You'll have noticed that the JSON structure above uses an object for the row data, so we also need to tell each column which property in the object to use as its data source to display - this is done with columns.data. Our resulting table initialisation looks like this:

new DataTable('#audiobooks', {
    ajax: './data.json',
    columns: [
        { data: 'title', title: 'Title' },
        { data: 'author', title: 'Author' },
        {
            data: 'releaseDate',
            title: 'Release Date',
            render: DataTable.render.date(),
        },
        {
            data: 'price',
            title: 'Price',
            render: DataTable.render.number(null, null, 2, '$'),
        },
        {
            data: 'finished',
            title: 'Finished',
            render: finished => finished ? '✓' : '⏳',
        },
    ]
});

You might notice I've added an extra column compared to the HTML example - a boolean data point which uses a custom renderer to decide what value should be shown to the end user!

Looking good

That's all you need to do to load JSON based data via Ajax into your DataTables. The completed example can be seen here:

This is just the start

You've seen here how you can quickly add interactivity to a static HTML table, and how you can create a dynamic table loaded via Ajax with ease! But this only scratches the surface of what DataTables can do.

For your next steps:

This quick start guide is new! If you've followed along and have any feedback, please get in touch, so it can be improved to help others as well!