Value Formatters

Value formatters allow you to format values for display. This is useful when data is one type (for example, numeric) but needs to be converted for human reading (for example, putting in currency symbols and number formatting). Note that it does not change the data, only how it appears in the grid.

• valueFormatter (function) A function or expression to format a value, should return a string. Not used for CSV export or copy to clipboard, only for UI cell rendering.

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

You can supply your own custom function for displaying values, or you can use the functions defined in d3-format and the d3-time-format libraries (See D3 Value Formatters).

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, for example 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

In this example note that:

• The "Account" column displays the text in upper case
• The "Balance" column prepends a $ sign before the number
• The "Name" column displays the name within other text
• The "Grade" column displays the number grades as either "Pass" or "Fail"
• The valueFormatter of each column is defined to handle missing data

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).

• useValueFormatterForExport ( Boolean, default: True) By default, values are formatted using the column's valueFormatter when exporting data from the grid. This applies to CSV and Excel export, as well as clipboard operations and the fill handle. Set to False to prevent values from being formatted for these operations. Regardless of this option, if custom handling is provided for the export operation, the value formatter will not be used.

Using useValueFormatterForExport applies to the following features:

• Copy/Cut (Enterprise feature)
• Fill Handle (Enterprise feature)
• Copy Range Down (Enterprise feature)
• CSV Export
• Excel Export (Enterprise feature)

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 shows the difference disabling or not the Value Formatter when exporting the data in CSV:

• By default, the data is formatted using the valueFormatter functions.
• Setting defaultColDef={"useValueFormatterForExport": False}, the data will not be formatted when exporting.