Expand All

  Getting Started

  Interfacing

  Features

  Row Models

  Themes

  Components

  Examples

  Third Party

Misc

Github stars make projects look great. Please help, donate a star, it's free.
Read about ag-Grid's Partnership with webpack.
Get informed on releases and other ag-Grid news only - never spam.
Follow on Twitter

Getters, Setters, Formatters & Parsers

The grid displays values from your data. The easiest way to configure this is to set colDef.field. The grid then pulls the gets and sets (after editing) the data to this location and does not formatting for the value.

// the grid is told to use the 'country' field for this column
var countryColDef = {
    field: 'country',
    ...
}

You should use colDef.field most of the time. However you may require to get/set the data another way, or you may wish to format (for display) or parse (after editing) the data if you do not display the data 'as is'. For these reasons, the grid provides the following additional methods:

Column Definition Properties for Getters, Setters, Formatters & Parsers

valueGetter(params) Function or expression. Gets the value from your data for display.
valueSetter(params) Function or expression. Sets the value into your data for saving. Return true if the data changed.
valueFormatter(params) Function or expression. Formats the value for display.
valueParser(params) Function or expression. Parses the value for saving.
headerValueGetter(params) Function or expression. Gets the value for display in the header.
floatingCellFormatter(params) Function or expression. Formatter to use for a floating row. If missing, the normal valueFormatter will be used.

Example - Getters, Setters, Formatters, Parsers

The example below demonstrates valueGetter, valueSetter, valueFormatter and valueParser all using functions (expressions are explained in the next section). Some of the columns are editable. When you finish editing, the row data is printed to the console so you can take a look at the impact of the edits. The following should be noted from the demo:

You can provide all getters, setters, formatters and parsers as functions OR expressions. Both achieve the same when added to the column definitions. Expressions are explained in the next section.
  • Column 'Simple': This is a simple string column using field. It is a simple string column, so doesn't need any special treatment.
  • Column 'Bad Number': This is editable. The value start as numbers. However the numbers after editing are stored as strings. This is bad, we should store the values after editing as numbers.
  • Column 'Good Number': This is editable. The number is formatted for displaying using a valueFormatter and the result of editing is parsed to a number using valueParser.
  • Column 'Name': This is editable. The name value is a combination of firstName and lastName. A valueGetter is used to combine the parts for display, and a valueSetter is used for setting the parts back into the grid (eg if you type 'Sam Boots', then 'Sam' gets set as the first name and 'Boots' as the last name.
  • Column 'A', 'B', 'A+B': Columns A and B are simple number columns. Column A+B demonstrates using a valueGetter to calculate a value for display.

Value Getter Flow

The flow diagram below shows the flow of the value getter.

Value Setter Flow

The flow diagram below shows the flow of the value setter.

Value Getter

A valueGetter allows you to pull values from your data instead of using the standard colDef.field mechanism. The interface for valueGetter is as follows:

// function for valueGetter
function valueGetter(params: ValueGetterParams) => any;

// interface for params
interface ValueGetterParams {
    data: any, // the data you provided for this row
    node: RowNode, // the row node for this row
    colDef: ColDef, // the column def for this column
    column: Column, // the column for this column
    api: GridApi, // the grid API
    columnApi: ColumnApi, // the grid Column API
    context: any,  // the context
    getValue: (colId: string) => any  // a utility method, for getting other column values
}

// example value getter, adds two fields together
colDef.valueGetter = function(params) {
    return params.data.firstName + params.data.lastName;
}

Value Setter

A valueSetter is the inverse of a valueGetter, it allows you to put values into your data in a way other than using the standard colDef.field. The interface for valueSetter is as follows:

// function for valueSetter
function valueSetter(params: ValueSetterParams) => boolean;

// interface for params
interface ValueGetterParams {
    oldValue: any, // the value before the change
    newValue: any, // the value after the change
    data: any, // the data you provided for this row
    node: RowNode, // the row node for this row
    colDef: ColDef, // the column def for this column
    column: Column, // the column for this column
    api: GridApi, // the grid API
    columnApi: ColumnApi, // the grid Column API
    context: any  // the context
}

// example value setter, put into a particular part of the data
colDef.valueSetter = function(params) {
    // see if values are different, if you have a complex object,
    // it would be more complicated to do this.
    if (params.oldValue!==params.newValue) {
        params.data[someField] = params.newValue;
        // get grid to refresh the cell
        return true;
    } else {
        // no change, so no refresh needed
        return false;
    }
}

Value Formatter

A valueFormatter allows you to format the value for display purposes. The interface for valueFormatter is as follows:

// function for valueFormatter
function valueFormatter(params: ValueGetterParams) => any;

// interface for params
interface ValueFormatterParams {
    value: any, // the value before the change
    data: any, // the data you provided for this row
    node: RowNode, // the row node for this row
    colDef: ColDef, // the column def for this column
    column: Column, // the column for this column
    api: GridApi, // the grid API
    columnApi: ColumnApi, // the grid Column API
    context: any  // the context
}

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

Value Formatter vs Cell Renderer

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

The answer is: valueFormatter's are for text formatting. cellRenderer's 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 valueFormatter, if you want to put buttons or HTML links use a cellRenderer. It is possible to use a combination of both, in which case the result of the valueFormatter will be passed to the cellRenderer.

Value Parser

A valueParser allows you to parse values after an edit (or after the user sets a value using the grid API). The interface for valueParser is as follows:

// function for valueParser
function valueParser(params: ValueParserParams) => any;

// interface for params
interface ValueParserParams {
    oldValue: any, // the value before the change
    newValue: any, // the value after the change
    data: any, // the data you provided for this row
    node: RowNode, // the row node for this row
    colDef: ColDef, // the column def for this column
    column: Column, // the column for this column
    api: GridApi, // the grid API
    columnApi: ColumnApi, // the grid Column API
    context: any  // the context
}

// example value parser, convert a string to a number
colDef.valueParser = function(params) {
    // this is how to convert a string to a number using JavaScript
    return Number(params.value);
}

Header Value Getters

Use headerValueGetter instead of colDef.headerName to allow dynamic header names.

The parameters for headerValueGetter differ from standard valueGetter as follows:

  • Only one of column or columnGroup will be present, depending on whether it's a column or a column group.
  • Parameter location allows you to have different column names depending on where the column is appearing, eg you might want to have a different name when the column is in the column drop zone or the toolbar.

See the Tool Panel Example for an example of headerValueGetter used in different locations, where you can change the header name depending on where the name appears.

Floating Cell Formatter

Use floatingCellFormatter instead of colDef.cellFormatter to allow different formatting for floating rows. If you don't specify a colDef.floatingCellFormatter, then cellFormatter will get used instead if it is present.

You can use the same formatter for floating rows and normal rows and check the row type. You can check if the row is floating by checking params.node.floating property.