DataTable

Once you have installed and registered DataTables you will have a <DataTable> component available for use in your JSX (you can change the name by changing the import statement if you prefer something else) - i.e.:

return (
    <DataTable />
);

On it's own, this is just an empty table and not very interesting! Next, we need to configure it with that columns we want to show, the data to be displayed and any configuration options to customise the table.

Child components

The <DataTable> component can be configured with three different types of children:

• <Column> components, exported by the DataTables React component. These can be used to define the columns to display and the data to display in each. Please see the <Column> component documentation for full details on its options and how to make use of it to display React elements.
• <thead> - a regular HTML table header
• <tfoot> - a regular HTML table footer.

The header and footer can be automatically generated from the <Column> components, and typically you won't need to use thead or tfoot, however, they can be useful if you wish to create "complex" headers and footers for your table which involve colspan and rowspan attributes - e.g.:

return (
    <DataTable>
        <thead>
            <tr>
                <th rowspan="2">Name</th>
                <th colspan="2">Position</th>
                <th colspan="3">Contact</th>
            </tr>
            <tr>
                <th colspan="3">HR info</th>
                <th colspan="2">Direct</th>
            </tr>
        </thead>
    </DataTable>
);

Important: Do not use a Javascript iteration statement (for, forEach, etc) in your JSX to populate the table with data unless the data is static (i.e. not reactive). Doing so would cause both DataTables and React to try and control the same DOM elements, resulting in unpredictable behaviour. Bind data using the data parameter!

Properties

To configure the DataTable, the component has the following properties that can be assigned for configuration:

• ajax - Ajax option for DataTables - to load data for the table over Ajax.
• className - Class name to assign to the table
• columns - Define the columns array used for DataTables initialisation - note you are unlikely to need this if you use the <Column> component!
• data - Data array for DataTables. This is optional and if you are using Ajax to load the DataTable this attribute should not be used.
• on* - Event functions - see the Events section below.
• options - The DataTables options for the table. Note that this can include columns, data and ajax - if they are provided by one of the properties from above that will override a matching option given here.
• ref - Get a reference to a DataTables API instance for the table. See the API section below.

Configuration options

The default DataTables configuration is simple and yet powerful, but you will likely wish to customise the UI that it presents on your page - for example to change the location of the search input bar, or to enable and configure extensions such as Buttons.

This is done through the options parameter which can take any of the DataTables configuration options:

function App() {
    const options = {
        layout: [
            top: 'search',
            topStart: null,
            topEnd: null
        ],
        pageLength: 25
    };

    return (
        <DataTable
            options={options}
        >
            ...
        </DataTable>
    );
}

In this case layout is used to remove the default search and page length controls, replacing them with a search input at the top of the table. The page length is also set to 25.

API

When working with DataTables, you will often want to use its API to unlock its full potential. This is possible through the ref attribute for the datatables.net-react component.

function App() {
    const table = useRef();

    return (
        <DataTable
            ajax="/data.json"
            ref={table}
        >
            <Column title="Name" data="name" />
            <Column title="Position" data="position" />
            <Column title="Office" data="office" />
            <Column title="Extn." data="extn" />
            <Column title="Start date" data="start_date" />
            <Column title="Salary" data="salary" />
        </DataTable>
    );
}

The ref has an object that contains access to the DataTables through the dt() function - e.g.:

console.log(
    table.current.dt().page.info()
);

Example: API access and usage.

Events

DataTables emits a large number of events which can be useful to listen for and react to when the events happen. With the DataTables / React component, you can listen for the events using an on* property (where the full name is defined by the event name in camelCase form and prefixed with on):

<DataTable
    ajax="/data.json"
    onXhr={xhrEvent}
    onDraw={drawEvent}
>
    <Column ... />
</DataTable>

This will listen for xhr and draw, calling the functions as given. The events will be given the same arguments as described in the DataTables documentation.

Example: Listening for events.