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.
Provided Components
The grid comes with some built in Cell Components that cover some common cell rendering requirements.
Group Cell Component: For showing group details with expand & collapse functionality when using any of Row Grouping, Master Detail or Tree Data.
Animate Change Cell Renderers: For animating changes when data is updated.
Checkbox Cell Renderer: For displaying boolean values with a checkbox when
cellDataType
of Boolean is used.
Custom Components
The Component is provided props
containing, amongst other things, the value to be rendered.
// this comp gets inserted into the Cell
const CustomButtonComp = props => {
return <>{props.value}</>;
};
The provided props
(interface CustomCellRendererProps) are:
Value to be rendered. |
Formatted value to be rendered. |
True if this is a full width row. |
Pinned state of the cell. |
The row's data. Data property can be undefined when row grouping or loading infinite row models. |
The row node. |
The cell's column definition. |
The cell's column. |
The grid's cell, a DOM div element. |
The parent DOM item for the cell renderer, same as eGridCell unless using checkbox selection. |
Convenience function to get most recent up to data value. |
Convenience function to set the value. |
Convenience function to format a value using the column's formatter. |
Convenience function to refresh the cell. |
registerRowDragger:
rowDraggerElement The HTMLElement to be used as Row Dragger
dragStartPixels The amount of pixels required to start the drag (Default: 4)
value The value to be displayed while dragging. Note: Only relevant with Full Width Rows.
suppressVisibilityChange Set to true to prevent the Grid from hiding the Row Dragger when it is disabled.
|
Sets a tooltip to the main element of this component.
value The value to be displayed by the tooltip
shouldDisplayTooltip A function returning a boolean that allows the tooltip to be displayed conditionally. This option does not work when enableBrowserTooltips={true} .
|
The grid api. |
Application context as set on gridOptions.context . |
Note that if Row Selection is enabled, it is recommended to set suppressKeyboardEvent
on the column definition to prevent the ␣ Space key from triggering both row selection and toggling the checkbox.
Selecting Components
The Cell Component for a Column is set via colDef.cellRenderer
and can be any of the following types:
String
: The name of a registered Cell Component, see Registering Custom ComponentsComponent
: Direct reference to a Cell Component.Inlined Component
: An inlined Cell Component.
The code snippet below demonstrates each of these method types.
const [columnDefs] = useState([
// 1 - String - The name of a Cell Component registered with the grid.
{
field: 'age',
cellRenderer: 'agGroupCellRenderer',
},
// 2 - Component - Provide your own Cell Component directly without registering.
{
field: 'sport',
cellRenderer: MyCustomCellRendererClass,
},
// 3 - Inlined Component
{
field: 'year',
cellRenderer: props => {
// put the value in bold
return <>Value is <b>{params.value}</b></>;
}
}
]);
Dynamic Component Selection
The colDef.cellRendererSelector
function allows setting different 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 row's 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
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)
.
Returns the list of active cell renderer instances. |
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 methodmedalUserFunction()
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.
Note that the hook version of the above example makes use of useImperativeHandle
to expose methods to the grid (and other components). Please refer to the hook specific documentation for more information.
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 ColourCellComp = props => <span style={{color: props.color}}>{props.value}</span>;
const GridExample = () => {
const [columnDefs] = useState([
{
headerName: "Colour 1",
field: "value",
cellRenderer: ColourCellComp,
cellRendererParams: {
color: 'guinnessBlack'
}
},
{
headerName: "Colour 2",
field: "value",
cellRenderer: ColourCellComp,
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.
Dynamic Tooltips
When working with Custom Cell Renderers it is possible to register custom tooltips that are displayed dynamically by using the setTooltip
method.
Properties available on the CustomCellRendererProps<TData = any, TValue = any, TContext = any>
interface.
Sets a tooltip to the main element of this component.
value The value to be displayed by the tooltip
shouldDisplayTooltip A function returning a boolean that allows the tooltip to be displayed conditionally. This option does not work when enableBrowserTooltips={true} .
|
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.
Keyboard Navigation
When using custom Cell Components, the custom Cell Component is responsible for implementing support for keyboard navigation among its focusable elements. This is why by default, focusing a grid cell with a custom Cell Component will focus the entire cell instead of any of the elements inside the custom cell renderer.
In order to handle focus in your custom cell component, implement Custom Cell Component Keyboard Navigation.