JavaScript Data GridCell Data Types

Working with values of different data types is made easy by using cell data types.

This allows different grid features to work without any additional configuration, including Rendering, Editing, Filtering, Sorting, Row Grouping and Import & Export (CSV Export, Excel Export, Clipboard).

Enable Cell Data Types

There are six pre-defined cell data types: 'text', 'number', 'boolean', 'date', 'dateString' and 'object'.

These are enabled by default, with the data type being inferred from the row data if possible (see Inferring Data Types).

Specific cell data types can also be defined by setting the cellDataType property on the column definition.

const gridOptions = {
    columnDefs: [
        {
            field: 'athlete',
            // enables cell data type `text`
            cellDataType: 'text'
        }
    ],

    // other grid options ...
}

The following example demonstrates the six pre-defined cell data types (inferred from the row data):

• The Athlete column has a 'text' data type.
• The Age column has a 'number' data type.
• The Gold column has a 'boolean' data type.
• The Date column has a 'date' data type (cell values are Date objects).
• The Date (String) column has a 'dateString' data type (cell values are strings representing dates).
• The Country column has an 'object' data type. This also Overrides the Pre-Defined Cell Data Type Definition so that the value parser and formatter work with the object structure.

Inferring Data Types

By default the grid will infer cell data types the first time that row data is passed into the grid.

For inference to work for a column, it must contain non-null values and have the field property set. The resolved column definition (including the default column definition and column types) must also not have the Value Getter, Value Parser or reference data properties set, or be using Sparklines. If these conditions are not met, no cell data type will be set (it will need to be defined directly on the column if desired).

Data type inference can be disabled by setting cellDataType = false on an individual column, or for all columns on the Default Column Definition.

Note that where inference is possible but it does not match any of the pre-defined cell data types, it will default to object.

Pre-Defined Cell Data Types

Each of the pre-defined cell data types work by setting specific column definition properties with default values/callbacks. This enables the different grid features to work correctly for that data type.

The column definition properties that are set based on the cell data type will override any in the Default Column Definition, but will be overridden by any Column Type properties as well as properties set directly on individual column definitions. Note that for filterParams, only nested properties on the default column definition will be overridden (rather than the entire object).

If you wish to override one of the properties set below for all types, you can do so by creating a Column Type, and assigning the column type to the Default Column Definition.

All the cell data types set the following (unless specified):

• A Value Parser to convert from string to the relevant data type.
• A Value Formatter to convert from the relevant data type to string (except for 'text').
• A Key Creator which uses the Value Formatter to allow Row Grouping to work (except for 'number' and 'text').

Note that when using cell data types, the Value Formatter will not run for values in group columns (as they have already been formatted), or for aggregated values where the data type can differ. To apply custom formatting in these cases, cell data types will need to be disabled for the underlying columns.

Text

The 'text' cell data type is used for string values. As most grid functionality works directly with string values, the 'text' cell data type does not set any properties outside of the ones specified above for all data types.

Number

The 'number' cell data type is used for number values.

The following properties are set:

• The Number Cell Editor is used for editing.
• When the Set Filter is Disabled, the Number Filter is used.
• When the Set Filter is Enabled, filterParams.comparator is set to Sort the Filter List.

To show only a certain number of decimal places, you can Override the Pre-Defined Cell Data Type Definition and provide your own Value Formatter. It is also possible to control the number of decimal places allowed during editing, by providing a precision to the Number Cell Editor.

Boolean

The 'boolean' cell data type is used for boolean values.

The following properties are set:

• The Checkbox Cell Renderer is used for rendering, which displays a checkbox. Set cellRendererParams.disabled=true for the checkbox to be read only.
• The Checkbox Cell Editor is used for editing (similar to the renderer).
• suppressKeyboardEvent is set to enable the ␣ Space key to toggle the renderer value.
• When the Set Filter is Disabled, the Text Filter is used, and filterParams is set to display a single dropdown with 'True'/'False' (or equivalents with Localisation).
• When the Set Filter is Enabled, filterParams.valueFormatter is set to show 'True'/'False' (or equivalents with Localisation).

Date

The 'date' cell data type is used for date values that are represented as Date objects.

The default Value Parser and Value Formatter use the ISO string format 'yyyy-mm-dd'. If you wish to use a different date format, then you can Override the Pre-Defined Cell Data Type Definition.

The following properties are set:

• The Date Cell Editor is used for editing.
• When the Set Filter is Enabled, the Set Filter Tree List is enabled, and the Values are Formatted by setting filterParams.treeListFormatter to convert the months to names and filterParams.valueFormatter to format the Floating Filter values using the Value Formatter.

Date as String

The 'dateString' cell data type is used for date values that are represented as string values.

This data type uses the ISO string format 'yyyy-mm-dd'. If you wish to use a different date format, then you can Override the Pre-Defined Cell Data Type Definition.

The following properties are set:

• The Date as String Cell Editor is used for editing.
• When the Set Filter is Disabled, the Date Filter is used, and filterParams.comparator is set to parse the string date values.
• When the Set Filter is Enabled, the Set Filter Tree List is enabled, with filterParams.treeListPathGetter set to convert the string date values into paths, and the Values are Formatted by setting filterParams.treeListFormatter to convert the months to names and filterParams.valueFormatter to format the Floating Filter values using the Value Formatter.

Object

The 'object' cell data type is used for values that are complex objects (e.g. none of the above data types).

If you have different types of complex object, you will want to Provide Custom Cell Data Types.

The following properties are set:

• cellEditorParams.useFormatter = true so that the cell editor uses the Value Formatter.
• A comparator is defined to allow Custom Sorting using the Value Formatter.
• When the Set Filter is Disabled, a Filter Value Getter is used to convert the value with the Value Formatter.
• When the Set Filter is Enabled, filterParams.valueFormatter is set to format the values using the Value Formatter.

Pre-Defined Cell Data Type Example

The Enable Cell Data Types Example above demonstrates each of the different pre-defined cell data types with AG Grid Community.

The example below shows the same data types in AG Grid Enterprise:

• Row grouping is enabled allowing each of the fields to be grouped on.
• Import/Export features are enabled allowing the following:
  • Clipboard (copy/paste)
  • Fill handle
  • CSV/Excel export

Providing Custom Cell Data Types

Custom cell data types can be added by setting the grid option dataTypeDefinitions.

const gridOptions = {
    dataTypeDefinitions: {
        percentage: {
            extendsDataType: 'number',
            baseDataType: 'number',
            valueFormatter: params => params.value == null
                ? ''
                : `${Math.round(params.value * 100)}%`,
        }
    },

    // other grid options ...
}

Each custom data type definition must have a baseDataType of one of the six Pre-Defined Cell Data Types, which represents the data type of the underlying cell values.

Data type definitions support inheritance via the extendsDataType property. Each custom cell data type must either extend one of the pre-defined types, or another custom type. Any non-overridden properties are inherited from the parent definition. To prevent inheriting properties from the parent definition, suppressDefaultProperties = true can be set on the definition.

Column Types can be set via the columnTypes property to allow other column definition properties to be set for the data type. By default these will replace any column types against the parent definition. To allow these to be appended to the parent definition column types, appendColumnTypes = true can be set.

To allow Inferring Cell Data Types to work for custom types, the dataTypeMatcher property can be set. This returns true if the value is of the correct type. Note that the data type matchers will be called in the order they are provided in dataTypeDefinitions (for custom only), and then the pre-defined data type matchers will be called.

The following example demonstrates providing custom cell data types:

• The Country column contains complex objects and has a cell data type of 'country'.
• The Sport column contains a different type of complex object and has a cell data type of 'sport'.
• The dataTypeMatcher callback is defined for both cell data types to allow inferring the type.

Overriding the Pre-Defined Cell Data Type Definitions

The default properties for the Pre-Defined Cell Data Types can be overridden if desired.

For example, this is required if a different date format is desired.

This works in the same way as when Providing Custom Cell Data Types.

const gridOptions = {
    dataTypeDefinitions: {
        // override `date` to handle custom date format `dd/mm/yyyy`
        date: {
            baseDataType: 'date',
            extendsDataType: 'date',
            valueParser: params => {
                if (params.newValue == null) {
                    return null;
                }
                // convert from `dd/mm/yyyy`
                const dateParts = params.newValue.split('/');
                return dateParts.length === 3 ? new Date(
                    parseInt(dateParts[2]),
                    parseInt(dateParts[1]) - 1,
                    parseInt(dateParts[0])
                ) : null;
            },
            valueFormatter: params => {
                // convert to `dd/mm/yyyy`
                return params.value == null
                    ? ''
                    : `${date.getDate()}/${date.getMonth() + 1}/${date.getFullYear}`;
            },
        }
    },

    // other grid options ...
}

The following example demonstrates overriding pre-defined cell data types:

• The Date column is of type 'dateString' which has been overridden to use a different date format (dd/mm/yyyy).
• The data type definition for 'dateString' provides a dateParser and dateFormatter as it is a Date as String Data Type Definition.

Date as String Data Type Definition

If overriding 'dateString' due to a different date format, then a couple of extra properties need to be set to handle conversion between Date objects and the desired string format.