JavaScript Data GridValue Formatters
javascript logo

Value formatters allow you to format values for display. This is useful when data is one type (e.g. numeric) but needs to be converted for human reading (e.g. putting in currency symbols and number formatting).

Below shows the column definition properties for value formatters.

// example value formatter, simple currency formatter
colDef.valueFormatter = params => {
    return '£' + params.value;
}

If using Cell Data Types, value formatters are set by default to handle the display of each of the different data types.

Value Formatter vs Cell Renderer

A cell renderer allows you to put whatever HTML you want into a cell. This sounds like value formatters and a cell renderers have cross purposes, so you may be wondering, when do you use each one and not the other?

The answer is that value formatters are for text formatting and cell renderers are for when you want to include HTML markup and potentially functionality to the cell. So for example, if you want to put punctuation into a value, use a value formatter, but if you want to put buttons or HTML links use a cell renderer. It is possible to use a combination of both, in which case the result of the value formatter will be passed to the cell renderer.

Be aware that the Value Formatter params won't always have 'data' and 'node' supplied, e.g. the params supplied to the Value Formatter in the Set Filter. As a result favour formatter implementations that rely upon the 'value' argument instead, as this will lead to better reuse of your Value Formatters.

Value Formatter Example

The example below shows value formatters in action.

  • Columns A and B display the value of the field property
  • Columns £A and £B use a currencyFormatter to display the value as a currency
  • Columns(A) and (B) use a bracketsFormatter to display the value inside brackets

Use Value Formatter for Export

By default, the grid uses the value formatter when performing other grid operations that need values in string format.

This behaviour can be prevented by setting the column definition property useValueFormatterForExport = false (note this does not apply to rendering).

Using the value formatter for export applies to the following features:

Using a value formatter for export is normally used in conjunction with Using a Value Parser for Import, where a Value Parser is defined that does the reverse of the value formatter.

The following example demonstrates the default behaviour using the value formatter for export with each of the supported features mentioned above.

Note that if any of the following conditions are true, then useValueFormatterForExport is ignored for that feature and the value will be either the original value or that set in the custom handler:

  • If processCellForClipboard is provided when using copy/cut.
  • If fillOperation is provided when using fill handle.
  • If processCellForClipboard is provided when using copy range down.
  • If processCellCallback is provided when using CSV export.
  • If processCellCallback or Excel Data Types are provided when using Excel export.
  • If the underlying value is a number when using Excel export. To export formatted number values to Excel, please use the Excel Data Type feature.