Cell Rendering

By default the grid renders values into the cells as strings. If you want something more complex you use a cell renderer.

The cell editor for a column is set via colDef.cellRenderer and can be any of the following types:

  1. undefined / null: Grid renders the value as a string.
  2. String: The name of a cell renderer registered with the grid.
  3. Class: Provide your own cell renderer component directly without registering.
  4. Function: A function that returns either an HTML string or DOM element for display.
The code snippet below demonstrates each of these method types.

// 1 - undefined / null - Grid renders the value as a string. var colDef1 = { cellRenderer: null, ... } // 2 - String - The name of a cell renderer registered with the grid. var colDef2 = { cellRenderer: 'agGroupCellRenderer', ... } // 3 - Class - Provide your own cell renderer component directly without registering. var colDef3 = { cellRenderer: MyCustomCellRendererClass, ... } // 4 - Function - A function that returns an HTML string or DOM element for display var colDef3 = function(params) { // put the value in bold return 'Value is <b>'+params.value+'</b>'; }

This remainder of this documentation page goes through the grid provided cell renderer's. To build your own cell renderer see the section Cell Rendering Components.

No Cell Renderer

If you have no requirements for custom cells, then you should use no cell renderer. Having no custom cell renderers will result in the fastest possible grid (which might be important to you if using Internet Explorer) as even the simplest cell renderer will result in some extra div's in the DOM.

If you just want to do simple formatting of the data (eg currency or date formatting) then you can use colDef.valueFormatter.

Many Renderers One Column

It is also possible to use different renderers for different rows in the same column. Typically an application might check the rows contents and choose a renderer accordingly. To configure this set colDef.cellRendererSelector to a function that returns the name of the component to be used as a renderer and optionally the custom params to be passed into it

The parameters that this functions will receive the same parameters than a renderer would receive:

The following example illustrates how to use different renderers and parameters in the same column. Note that:

  • The column 'Value' holds data of different types as shown in the column 'Type' (numbers/genders/moods).
  • colDef.cellRendererSelector is a function that selects the renderer based on the row data
    • cellRendererSelector:function (params) { var moodDetails = { component: 'moodCellRenderer' }; var genderDetails = { component: 'genderCellRenderer', params: {values: ['Male', 'Female']} }; if (params.data.type === 'gender') return genderDetails; else if (params.data.type === 'mood') return moodDetails; else return null; }
  • The column 'Rendered Value' show the data rendered applying the component and params specified by colDef.cellRendererSelector

Grid Provided Renderers

The grid comes with three built-in renderers which are:

  • agGroupCellRenderer: For displaying group values with expand / collapse functionality.
  • agAnimateShowChangeCellRenderer and agAnimateSlideCellRenderer: For animating changes in data.

The following sections goes through each one in detail.

Grid Renderers - agAnimateShowChangeCellRenderer and agAnimateSlideCellRenderer

The grid provides two cell renderers for animating changes to data. They are:

  • agAnimateShowChangeCellRenderer: The previous value is temporarily shown beside the old value with a directional arrow showing increase or decrease in value. The old value is then faded out.
  • agAnimateSlideCellRenderer: The previous value shown in a faded fashion and slides, giving a ghosting effect as the old value fades adn slides away.

The example below shows both types of animation cell renders in action. To test, try the following:

  • Columns A, B and C are editable.
  • Columns D and E are updated via clicking the button.
  • Changes to any of the first 5 columns results in animations in the Total and Average column.
  • Changes to D and E also result in animations.
We hope you like the animation cell renderers. However you can also take inspiration from them, and create your own animations in your own cell renderers. Check out our source code on Github on how we implemented these cell renderers for inspiration. Most of the ag-Grid users love the animateShowChange cell renderer for showing changes in values. Not many people like the animateSlide one. So if you are trying to impress someone, probably best show them the animateShowChange :)

Grid Renderer - agGroupCellRenderer

If you are grouping in the grid, then you will need to provide a group cell renderer as the group cell renderer is what provides the user with the expand and collapse functionality.

The grid's group cell renderer takes many parameters to configure it. Here is an example of a column and it's configuration:

colDef = { // tell the grid we want to show group values in this column showRowGroup: true, // set the cell renderer to 'group' cellRenderer:'agGroupCellRenderer', // provide extra params to the cellRenderer cellRendererParams: { suppressCount: true, // turn off the row count suppressDoubleClickExpand: true, // turn off double click for expand checkbox: true, // enable checkbox selection innerRenderer: myInnerRenderer, // provide an inner renderer footerValueGetter: myFooterValueGetter // provide a footer value getter } ... };

The set of parameters for the group cell renderer are:

  • suppressCount: One of [true, false], if true, count is not displayed beside the name.
  • checkbox: One of [true,false], if true, a selection checkbox is included.
  • suppressPadding: Set to true to node including any padding (indentation) in the child rows.
  • innerRenderer: The renderer to use for inside the cell (after grouping functions are added).
  • footerValueGetter: The value getter for the footer text. Can be a function or expression.
  • suppressDoubleClickExpand: If true then double clicking will not expand the group.

Example Group cellRenderer

Below shows an example of configuring a group cell renderer. The example setup is not realistic as it has many columns configured for the showing the groups. The reason for this is to demonstrate different group column configurations side by side. In your application, you will typically have one column for showing the groups.

The example is built up as follows:

  • The data is grouped by two columns: Type (one of 'Fiction' or 'Non-Fiction') and Country (a country name, eg Ireland or United Kingdom).
  • The column 'Country Group - No Renderer' configures the grid to put the 'Country' group data only into this column by setting showRowGroup='country'. All rows that are not this group are blank. There is no cell renderer configured, so the grid just places the text for the group into the cell, there is not expand / collapse functionality.
  • The column 'All Groups - no Renderer' builds on before, but adds all groups by setting showRowGroup=true. This gets the column to display all groups, but again no cell renderer so not expand / collapse functionality.
  • The column Group Renderer A builds on before, but adds the group cell renderer with cellRenderer='group'. The values are exactly as per the previous column, except now we have expand and collapse functionality.
  • The column Group Renderer B builds on before, but adds field=city so that the city is displayed in the leave nodes in the group column.
  • The column Group Renderer C builds on before, but adds the following cellRendererParams:
    • suppressCount=true: Suppresses the row count.
    • suppressDoubleClickExpand=true: Suppress double click for expanding.
    • checkbox=true: Adds a selection checkbox.
    • padding=20: Changes the padding (indentation) of the levels.
    • innerRenderer=SimpleCellRenderer: Puts custom rendering for displaying the value. The group cellRenderer will take care of all the expand / collapse, selection etc, but then allow you to customise the display of the value. In this example we add a border when the value is a group, and we add the Ireland Ireland flag (because Niall Crosby is from Ireland) to the leaf levels.
If you don't like the grid provided group cell renderer, you can build your own cell renderer and provide the grouping functionality. If you do this, then take a look at the grid's source code and see how we implemented the ag-Grid group cell renderer.