You can create your own Custom Components to customise the behaviour of the grid. For example you can customise how cells are rendered, how values are edited and also create your own filters.
The full list of component types you can provide in the grid are as follows:
- Cell Component: To customise the contents of a cell.
- Header Component: To customise the header of a column and column groups.
- Edit Component: To customise the editing of a cell.
- Filter Component: For custom column filter that appears inside the column menu.
- Floating Filter: For custom column floating filter that appears inside the column menu.
- Date Component: To customise the date selection component in the date filter.
- Loading Component: To customise the loading cell row when using Server Side row model.
- Overlay Component: To customise loading and no rows overlay components.
- Status Bar Component: For custom status bar components.
- Tool Panel Component: For custom tool panel components.
- Tooltip Component: For custom cell tooltip components.
The remainder of this page gives information that is common across all the component types.
Registering Custom Components
In previous versions of the grid, custom components were declared in an imperative way. See Migrating to Use reactiveCustomComponents for details on how to migrate to the current format.
There are two ways to register custom components:
- Direct reference.
- By name.
1. By Direct Reference
When registering a React Component by reference you simply pass the Component to the place you want it used (i.e. Cell Renderer, Filter etc).
In this example we're specifying that we want our React CubeComponent
as a Cell Renderer in the Cube
column:
//...other imports
import CubeComponent from './CubeComponent';
const GridExample = () => {
// other properties & methods
const columnDefs = useMemo( () => [{field: 'value', cellRenderer: CubeComponent}], []);
return (
<AgGridReact
columnDefs={columnDefs}
...other properties
/>
);
};
The advantage of referencing Components directly is cleaner code, without the extra level of indirection added when referencing by name.
2. By Name
When registering a React component by name you need to first register the component within the grid components
property, then reference the component by name where you want it used (i.e. as a Cell Renderer, Filter etc).
In this example we've registered our React CubeComponent
and given it a name of cubeComponent
(this can be any name you choose). We then specify that we want the previously registered cubeComponent
to be used as a Cell Renderer in the Cube
column:
//...other imports
import CubeComponent from './CubeComponent';
const GridExample = () => {
// other properties & methods
const components = useMemo(() => ({
cubeComponent: CubeComponent
}), []);
const columnDefs = useMemo(() => [{field: 'value', cellRenderer: 'cubeComponent'}], []);
return (
<AgGridReact
components={components}
columnDefs={columnDefs}
...other properties
/>
);
};
The advantage of referencing components by name is definitions (eg Column Definitions) can be composed of simple types (ie JSON), which is useful should you wish to persist Column Definitions.
A React Component in this context can be any valid React Component - A Class Based Component, a Hook or even an inline Functional Component. The same rules apply regardless of the type of component used.
Providing Additional Parameters
Each Custom Component gets a set of parameters from the grid. For example, for Cell Component the grid provides, among other things, the value to be rendered. You can provide additional properties to the Custom Component (e.g. what currency symbol to use) by providing additional parameters specific to your application.
To provide additional parameters, use the property [prop-name]Params
, e.g. cellRendererParams
.
const [columnDefs, setColumnDefs] = useState([
{
field: 'price',
cellRenderer: PriceCellRenderer,
cellRendererParams: {
currency: 'EUR'
}
},
]);
<AgGridReact columnDefs={columnDefs} />
Mixing JavaScript and React
When providing Custom Components you have a choice of the following:
- Provide an AG Grid component as a React Component.
- Provide an AG Grid component in JavaScript (JavaScript Class Components only, not JavaScript Functional Components).
The following code snippet shows how both JavaScript and React Components can be used at the same time:
//...other imports
import JavascriptComponent from './JavascriptComponent.js';
import ReactComponent from './ReactComponent';
const GridExample = () => {
// JS and React components, only need register if looking up by name
const components = useMemo(() => ({
'javascriptComponent': JavascriptComponent,
'reactComponent': ReactComponent
}), []);
const columnDefs = useMemo( () => [
{
headerName: "JS Cell",
field: "value",
cellRenderer: 'javascriptComponent', // JS comp by Name
},
{
headerName: "JS Cell",
field: "value",
cellRenderer: JavascriptComponent, // JS comp by Direct Reference
},
{
headerName: "React Cell",
field: "value",
cellRenderer: 'reactComponent', // React comp by Name
},
{
headerName: "React Cell",
field: "value",
cellRenderer: ReactComponent, // React comp by Direct Reference
}
], []);
return (
<div className="ag-theme-quartz">
<AgGridReact
components={components}
columnDefs={columnDefs}
...other properties
/>
</div>
);
};
Change the documentation view to JavaScript to see how to create a plain JavaScript component.
Higher Order Components
If you use connect
to use Redux, or if you're using a Higher Order Component (HOC) to wrap the grid React component, you'll also need to ensure the grid can get access to the newly created component. To do this you need to ensure forwardRef
is set:
export default connect((state) => {
return {
currencySymbol: state.currencySymbol,
exchangeRate: state.exchangeRate
}
}, null, null, { forwardRef: true } // must be supplied for react/redux when using AgGridReact
)(PriceRenderer);
Component Usage
The below table gives a summary of the components, where they are configured and using what attribute.
Component | Where | Attribute |
---|---|---|
Cell Component | Column Definition | cellRenderer cellRendererParams cellRendererSelector |
Editor Component | Column Definition | cellEditor cellEditorParams cellEditorSelector |
Filter | Column Definition | filter filterParams |
Floating Filter | Column Definition | floatingFilter floatingFilterParams |
Header Component | Column Definition | headerComponent headerComponentParams |
Header Group Component | Column Definition | headerGroupComponent headerGroupComponentParams |
Tooltip Component | Column Definition | tooltipComponent tooltipComponentParams |
Group Row Cell Component | Grid Option | groupRowRenderer groupRowRendererParams |
Group Row Inner Cell Component | Grid Option | innerRenderer innerRendererParams |
Detail Cell Component | Grid Option | detailCellRenderer detailCellRendererParams |
Full Width Cell Component | Grid Option | fullWidthCellRenderer fullWidthCellRendererParams |
Loading Cell Component | Grid Option Column Definition | loadingCellRenderer loadingCellRendererParams |
Loading Overlay | Grid Option | loadingOverlayComponent loadingOverlayComponentParams |
No Rows Overlay | Grid Option | noRowsOverlayComponent noRowsOverlayComponentParams |
Drag and Drop Image | Grid Option | dragAndDropImageComponent dragAndDropImageComponentParams |
Date Component | Grid Option | dateComponent dateComponentParams |
Status Bar Component | Grid Option -> Status Bar | statusPanel statusPanelParams |
Tool Panel | Grid Option -> Side Bar | toolPanel toolPanelParams |
Menu Item | Grid Option -> Menu | menuItem menuItemParams |
Grid Provided Components
The grid comes with pre-registered components that can be used. Each component provided by the grid starts with the namespaces 'ag' to minimise naming conflicts with user provided components. The full list of grid provided components are in the table below.
Drag And Drop | |
---|---|
agDragAndDropImage | Default cover element when grid parts are being dragged |
Date Inputs | |
---|---|
agDateInput | Default date input used by filters |
Column Headers | |
---|---|
agColumnHeader | Default column header |
agColumnHeaderGroup | Default column group header |
Column Filters | |
---|---|
agSetColumnFilter (e) | Set filter (default when using AG Grid Enterprise) |
agTextColumnFilter | Simple text filter (default when using AG Grid Community) |
agNumberColumnFilter | Number filter |
agDateColumnFilter | Date filter |
agMultiColumnFilter (e) | Multi filter |
agGroupColumnFilter (e) | Group column filter |
Floating Filters | |
---|---|
agSetColumnFloatingFilter (e) | Floating set filter |
agTextColumnFloatingFilter | Floating text filter |
agNumberColumnFloatingFilter | Floating number filter |
agDateColumnFloatingFilter | Floating date filter |
agMultiColumnFloatingFilter (e) | Floating multi filter |
agGroupColumnFloatingFilter (e) | Floating group column filter |
Cell Components | |
---|---|
agAnimateShowChangeCellRenderer | Cell Component that animates value changes |
agAnimateSlideCellRenderer | Cell Component that animates value changes |
agGroupCellRenderer | Cell Component for displaying group information |
agLoadingCellRenderer (e) | Cell Component for loading row when using Enterprise row model |
agSkeletonCellRenderer (e) | Cell Component for displaying skeleton cells |
agCheckboxCellRenderer | Cell Component that displays a checkbox for boolean values |
Overlays | |
---|---|
agLoadingOverlay | Loading overlay |
agNoRowsOverlay | No rows overlay |
Cell Editors | |
---|---|
agTextCellEditor | Text cell editor |
agSelectCellEditor | Select cell editor |
agRichSelectCellEditor (e) | Rich select editor |
agLargeTextCellEditor | Large text cell editor |
agNumberCellEditor | Number cell editor |
agDateCellEditor | Date cell editor |
agDateStringCellEditor | Date represented as string cell editor |
agCheckboxCellEditor | Checkbox cell editor |
Master Detail | |
---|---|
agDetailCellRenderer (e) | Detail panel for master / detail grid |
Column Menu / Context Menu | |
---|---|
agMenuItem (e) | Menu item within column or context menu |
Overriding Grid Components
It is also possible to override components. Where the grid uses a default value, this means the override component will be used instead. The default components, where overriding makes sense, are as follows:
- agDragAndDropImage: To change the default drag and drop image when dragging grid parts.
- agDateInput: To change the default date selection across all filters.
- agColumnHeader: To change the default column header across all columns.
- agColumnGroupHeader: To change the default column group header across all columns.
- agLoadingCellRenderer: To change the default loading cell renderer for Enterprise Row Model.
- agSkeletonCellRenderer: To change the default skeleton loading cell renderer for Enterprise Row Model.
- agLoadingOverlay: To change the default 'loading' overlay.
- agNoRowsOverlay: To change the default 'no rows' overlay.
- agCellEditor: To change the default cell editor.
- agDetailCellRenderer: To change the default detail panel for master / detail grids.
- agMenuItem: To change the default menu item for column and context menus.
To override the default component, register the custom component in the GridOptions components
property under the above name.
const components = useMemo(() => (
{ agDateInput: CustomDateComponent,
agColumnHeader: CustomHeaderComponent
}), []);
<AgGridReact
components={components}
...other properties...
/>