Types

Table operations may differ best on the data that is present in the table and it is important that provides not only handling for the most common data types, but also methods by which new data types can be registered as the need for different data types arise in different applications. This document describes the data types build into DataTables and how to register additional data types.

What is a data type?

Each column in DataTables is assigned a specific "data type". The following operations vary depending on the data type:

  • Ordering (e.g. numbers, dates and strings all use different methods for ordering).
  • Search (e.g. deformatting a value such as a telephone number from a display value to a search term).
  • Default class name(s) for the column (e.g. numbers are right aligned, while text is left aligned by default).
  • Rendering.

The data type name is unique for each type, but a type can be used for multiple columns (or none if a table does not have matching data). To see what data type has been assigned to a column use the column().type() method.

When data is added to a table, DataTables will run the type detection methods for each data type to determine if the data in the column can be assigned a data type. If the data for all cells in a column match, the column will be assigned that data type. If no matching type is found, DataTables will always fallback to the string type.

Built in types

You can use the DataTable.types() method to determine what types are available to tables on the page. By default these are:

  • num - Plain numbers (e.g. 1, 8432).
  • num-fmt - Formatted numbers (e.g. $1'000, 8,000,000).
  • html-num - Plain numbers with HTML (e.g. 10).
  • html-num-fmt - Formatted numbers with HTML (e.g. _<em>€9.200,00</em>)
  • date - Dates in ISO8601 format (e.g. 2151-04-01).
  • html - HTML strings (e.g. <i>Tick</i>).
  • string-utf8 - Plain text strings with UTF-8 characters (e.g. Crème Brulée). 2.1.0
  • string - Plain text strings.

DataTables can also have additional data types registered through the built in DataTable.datetime() static method. This allows date/time strings of many different formats to be correctly ordered through the use of Moment.js or Luxon.

Registering new types

DataTables provides the static DataTable.type() method to allow registration of new data types, and also modification of existing data type properties. This method takes the data type name as the first parameter, and then a DataTables.Type object to define the data type. This must include a type detection function, and can also include functions for ordering data, formatting search terms, and automatic class assignment.

As an example, the following defines support for an IPv4 data type that is automatically detected:

DataTable.type('ipv4', {
    detect: function (data) {
        return typeof data === 'string' &&
            data.match(/^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$/)
                ? 'ipv4'
                : null;
    },
    order: {
        pre: function (data) {
            return Number(
                data
                    .split('.')
                    .map((num, idx) => num * Math.pow(2, (3 - idx) * 8))
                    .reduce((a, v) => ((a += v), a), 0)
            );
        }
    },
    className: 'dt-data-ipv4'
});

Please refer to the documentation for DataTables.Type for full details of the options that can be defined for registering new data types.

Modifying data type options

The built in data types are all registered using the method above, and it allows not only registration of types, but also modification. This lets you customise the built in data types if needed (for example an additional class name). This is done by passing in a partial object for a data type that is already defined.

As an example, the following will set a class name of numeric to be used on any cells which are found to contain numeric data:

DataTable.type('num', {
    className: 'numeric'
});

As before, please refer to DataTables.Type for the full set of options that can be set for a data type.