Cell Components

Custom HTML / DOM inside Cells is achieved using Cell Components. Create Custom Cell Components to have any HTML markup in a cell. The grid comes with some Provided Cell Components for common grid tasks.

The example below shows adding images, hyperlinks, and buttons to a cell using Custom Cell Components.

Custom Components

The interface for the Cell Component is as follows:

interface ICellRendererComp {
   // Optional - props for rendering.
   init?(props: ICellRendererParams): void;

   // Mandatory - Return the DOM element of the component, this is what the grid puts into the cell
   getGui(): HTMLElement;

   // Optional - Gets called once by grid after rendering is finished - if your renderer needs to do any cleanup,
   // do it here
   destroy?(): void;

   // Mandatory - Get the cell to refresh. Return true if the refresh succeeded, otherwise return false.
   // If you return false, the grid will remove the component from the DOM and create
   // a new component in its place with the new values.
   refresh(params: ICellRendererParams): boolean;
}

The Component is provided props containing, amongst other things, the value to be rendered.

class CustomButtonComponent {
    // ...
    init(props) {
        // create the cell
        this.eGui = document.createElement('div');
        this.eGui.innerHTML = props.value;
    }
    // ...
}

The provided props (interface ICellRendererParams) are:

Provided Components

The grid comes with some Cell Components out of the box. These Provided Cell Components cover common some common complex cell rendering requirements.

• Group Cell Component: For showing group details with expand & collapse functionality when using any of the Row Grouping, Master Detail or Tree Data.

• Show Change Cell Renderers: For animating changes when data is changing.

• Checkbox Cell Renderer: For displaying boolean values with a checkbox when cellDataType of Boolean is used.

Selecting Components

The Cell Component for a Column is set via colDef.cellRenderer and can be any of the following types:

1. String: The name of a registered Cell Component.*
2. Class: Direct reference to a Cell Component.
3. Function: A function that returns either an HTML string or DOM element for display.

*If referenced by name then the Cell Component must first be registered.

The code snippet below demonstrates each of these method types.

const gridOptions = {
    columnDefs: [
        // 1 - String - The name of a Cell Component registered with the grid.
        {
            field: 'age',
            cellRenderer: 'agGroupCellRenderer',
        },
        // 2 - Class - Provide your own Cell Component directly without registering.
        {
            field: 'sport',
            cellRenderer: MyCustomCellRendererClass,
        },
        // 3 - Function - A function that returns an HTML string or DOM element for display
        {
            field: 'year',
            cellRenderer: params => {
                // put the value in bold
                return 'Value is <b>' + params.value + '</b>';
            }
        }
    ],

    // other grid options ...
}

Dynamic Selection

The colDef.cellRendererSelector function allows setting difference Cell Components for different Rows within a Column.

The params passed to cellRendererSelector are the same as those passed to the Cell Renderer Component. Typically the selector will use this to check the rows contents and choose a renderer accordingly.

The result is an object with component and params to use instead of cellRenderer and cellRendererParams.

This following shows the Selector always returning back a Mood Cell Renderer:

cellRendererSelector: params => {
   return {
       component: GenderCellRenderer,
       params: {values: ['Male', 'Female']}
   };
}

However a selector only makes sense when a selection is made. The following demonstrates selecting between Mood and Gender Cell Renderers:

cellRendererSelector: params => {

   const type = params.data.type;

   if (type === 'gender') {
       return {
           component: GenderCellRenderer,
           params: {values: ['Male', 'Female']}
       };
   }

   if (type === 'mood') {
       return {
           component: MoodCellRenderer
       };
   }

   return undefined;
}

Here is a full example.

• 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.
• The column 'Rendered Value' show the data rendered applying the component and params specified by colDef.cellRendererSelector

Custom Props

The props passed to the Cell Component can be complimented with custom props. This allows configuring reusable Cell Components - e.g. a component could have buttons that are optionally displayed via additional props.

Compliment props to a cell renderer using the Column Definition attribute cellRendererParams. When provided, these props will be merged with the grid provided props.

// define Cell Component to be reused
const myCellComp = params => `<span style="color: ${params.color}">${params.value}</span>`;

// use with a colour
colDef.cellRenderer = myCellComp;
colDef.cellRendererParams = {
   color: 'guinnessBlack'
}

// use with another colour
colDef.cellRenderer = myCellRenderer;
colDef.cellRendererParams = {
   color: 'irishGreen'
}

This example shows rendering an image with and without custom props and using custom props to pass a callback to a button. The Refresh Data button triggers the cell components to refresh by randomising the success data.

Cell Component Function

Instead of using a class component, it's possible to use a function for a Cell Component. The function takes the same parameters as the Cell Component init method in the class variant. The function should return back either a) a string of HTML or b) a DOM object.

Use the function variant of a Cell Component if you have no refresh or cleanup requirements (ie you don't need to implement the refresh or destroy functions).

Below are some simple examples of Cell Components provided as simple functions:

// put the value in bold
colDef.cellRenderer = params => `**${params.value.toUpperCase()}**`;

// put a tooltip on the value
colDef.cellRenderer = params => `<span title="the tooltip">${params.value}</span>`;

// create a DOM object
colDef.cellRenderer = params => {
   const eDiv = document.createElement('div');
   eDiv.innerHTML = '<span class="my-css-class"><button class="btn-simple">Push Me</button></span>';
   const eButton = eDiv.querySelectorAll('.btn-simple')[0];

   return eDiv;
}

Accessing Instances

After the grid has created an instance of a Cell Component for a cell it is possible to access that instance. This is useful if you want to call a method that you provide on the Cell Component that has nothing to do with the operation of the grid. Accessing Cell Components is done using the grid API getCellRendererInstances(params).

An example of getting the Cell Component for exactly one cell is as follows:

// example - get cell renderer for first row and column 'gold'
const firstRowNode = api.getDisplayedRowAtIndex(0);
const params = { columns: ['gold'], rowNodes: [firstRowNode] };
const instances = api.getCellRendererInstances(params);

if (instances.length > 0) {
   // got it, user must be scrolled so that it exists
   const instance = instances[0];
}

Note that this method will only return instances of the Cell Component that exists. Due to Row and Column Virtualisation, Cell Components will only exist for Cells that are within the viewport of the Vertical and Horizontal scrolls.

The example below demonstrates custom methods on Cell Components called by the application. The following can be noted:

• The medal columns are all using the user defined MedalCellRenderer. The Cell Component has an arbitrary method medalUserFunction() which prints some data to the console.
• The Gold method executes a method on all instances of the Cell Component in the gold column.
• The First Row Gold method executes a method on the gold cell of the first row only. Note that the getCellRendererInstances() method will return nothing if the grid is scrolled far past the first row showing row virtualisation in action.
• The All Cells method executes a method on all instances of all Cell Components.

Dynamic Tooltips

When working with Custom Cell Renderers it is possible to register custom tooltips that are displayed dynamically by using the setTooltip method.

The example below demonstrates a dynamic tooltip being displayed on Cell Components. The following can be noted:

• The Athlete column uses the shouldDisplayTooltip callback to only display Tooltips when the text is not fully displayed.