Usage guide

In the quick start guide you saw how to get DataTables installed and displaying data in your React app. Let's take that to the next level now and go into a bit more detail so you can see how to customise the table to your needs.

Table configuration

First up, let's consider how you can configure the DataTable to suit your needs. DataTables has a wide range of options - for example, the ability to set the default page length, control where table control elements are shown and language options. These can be set using the options parameter for the <DataTable> component:

export default function () {
    const options = {
        pageLength: 25,
        scrollY: true
    };

    return (
        <DataTable ajax="/api/data" options={options}>
            <Column ... />
        </DataTable>
    );
}

Here we use pageLength to set the default page length and scrollY to enable DataTables' scrolling mode. All of the configuration options for DataTables can be defined through this object allowing extensive customisation of the table display.

Ajax data

You might also have spotted that ajax is used in the above, rather than the data property. This property maps to DataTables' ajax option and instructs it to get the data to display in the table from a remote Ajax source. Depending on how your app works, you might find this to be a useful way of populating the table.

For more details on using DataTables options with the React component, please see the <DataTable> documentation.

Column options

We've already see above how the <Column> component can have properties defined - e.g. title and data. The most commonly used column options are available as properties, but there are a wide range of options available, such as setting the default visibility, if a column should be orderable, and more. These options can be provided through the options property for <Column> - e.g.:

export default function () {
    return (
        <DataTable data={rows}>
            <Column title="ID" data="id" options={{orderable: false, searchable: false}} />
        </DataTable>
    );
}

Components

Inevitably you will want to use React components in your table cells - adding event handlers, routes and so on. This is done by providing a function that returns the component as a child of the <Column> component. For example to create a button that has the row id:

export default function () {
    return (
        <DataTable data={rows}>
            <Column title="ID" data="id">
                {id => <Button id={id} />}
            </Column>
        </DataTable>
    );
}

Note that the data attribute is still set - this allows DataTables to use the value for ordering and search of data without rendering the JSX (good for performance!). You can also make use of the whole row of data if you need to (three parameters are passed into the function).

For more details, please see the <Column> documentation.

Styling

You might have noticed the use of the -dt postfix for the DataTables core package above. DataTables supports multiple different styling frameworks such as Bootstrap, Bulma and Fomantic UI, each with its own package. The -dt denotes the default styling for DataTable.

Use the DataTables download builder to get a list of the packages to for the styling integration you want.

To include the relevant CSS in your component, include the styling package with a /css postfix - e.g. for the Bootstrap 5 styling integration use:

import 'datatables.net-bs5/css';

Extensions

DataTables has a wide range of extensions which extend the capabilities of DataTables. This includes abilities such as advanced editing through Editor, Excel like navigation though KeyTable and AutoFill.

Let's take a look at the installation of two extensions - Buttons and CardView. This will show the basic principle of how to install DataTables extensions - the others all follow the same basic pattern, each with their own specific configuration options in the table initialisation object.

Buttons

The Buttons extension for DataTables provides a common framework to describe table control buttons. You can create custom buttons and also make use of the default buttons that Buttons ships with, including the ability to export the table's data to CSV, Excel and PDF.

To install Buttons use the download builder and select the Buttons package (along with any others). Here I'll assume you are using the default styling so the datatables.net-buttons-dt package is required.

// Javascript
import jszip from 'jszip';
import pdfmake from 'pdfmake';
import DataTable, { Column } from 'datatables.net-react';
import DtCore from 'datatables.net-dt';

// Styling
import 'datatables.net-dt/css';
import 'datatables.net-buttons-dt/css';

// Assign libraries
DataTable.use(DtCore);
DtCore.use(jszip, 'jszip');
DtCore.use(pdfmake, 'pdfmake');

Note that in this case we've included the JSZip and pdfmake libraries as well. These are used to provide the export file formats and need to be registered with DataTables' DataTable.use() method so they can be "seen" by the Buttons library.

To display the Buttons, we can use the layout option and define where we want the default buttons to display:

export default function () {
    return (
        <DataTable
          ajax={rows}
          className="display"
          options={{
            layout: {
              topStart: 'buttons',
            }
          }}
        >
          <Column title="Name" data="name" />
          // etc ...
        </DataTable>
    );
}

For more information on the Buttons library including controlling what buttons are shown and adding custom buttons, please see the Buttons manual.

Example: React DataTables with export buttons

CardView

DataTables features a number of "Plus" extensions, which are available as part of DataTables Plus - a suite of commercial extensions that extend the capabilities of the core library. One of these extensions is CardView, which will display the table rows as "cards" when the display is sufficiently narrow - ideal for mobile, tablets or even complex data grids on larger monitors such as shopping carts. You still get all the benefits of DataTables' advanced search, etc.

To install CardView, use the download builder and select the CardView extension and install as normal:

npm install datatables.net-cardview-dt

Then include the software in your app:

import DataTable, { Column } from 'datatables.net-react';
import DtCore from 'datatables.net-dt';
import 'datatables.net-cardview-dt';

// Styling
import 'datatables.net-dt/css';
import 'datatables.net-cardview-dt/css';

// Assign libraries
DataTable.use(DtCore);

And finally enable the cardView option in the options property:

export default function () {
    return (
        <DataTable
          ajax="/data.json"
          className="display"
          options={{
            cardView: true,
          }}
        >
          <Column title="Name" data="name" />
          // etc ...
        </DataTable>
    );
}

By default, CardView will activate automatically when the output is narrow, and then switch back to table view when the display is wide enough. This behaviour can be controlled and even buttons added to allow the end user to select which mode they wish to use.

Example: React DataTables with CardView

Next steps

The React component for DataTables unlocks the flexibility of DataTables with the power of React. This document has given you an overview of how to use the two together effectively, but there is of course still more to learn. The DataTables core documentation details the capabilities of DataTables, while the rest of the React DataTables documentation delves into how to use the components introduced here in more detail.