Expand All

  Getting Started

  Reference

  Features

  Row Models

  Themes

  Components

  Examples

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

Components

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 following sections show how to use your own components inside the grid.

Registering Custom Components

The pages for each component type (cell renderer, cell editor etc) contain examples on how to register and use each component type. However it is useful here to step back and focus on the component registration process which is common across all component types and all frameworks (React, Angular etc).

There are two ways to register custom components:

  1. By name.
  2. Direct reference.
Both options are fully supported by the grid, however the preferred options is by name as it's more flexible. All of the examples in the documentation use this approach. The direct reference approach is kept for backwards compatibility reasons as this was the original way to do it in ag-Grid.

1. By Name

A component is registered with the grid by providing it through the components grid property. The components grid property contains a map of 'component names' to 'component classes'. Components of all types (editors, renderers, filters etc) are all stored together and must have unique names.

gridOptions = { // register the components using 'components' grid property components: { // 'countryCellRenderer' is mapped to class CountryCellRenderer countryCellRenderer: CountryCellRenderer, // 'countryFilter' is mapped to class CountryFilter countryFilter: CountryFilter }, // then refer to the component by name columnDefs: [ { field: 'country', cellRenderer: 'countryCellRenderer', filter: 'countryFilter' }, ], ... }

2. Direct Reference

A shorter approach is to refer to the component class directly.

gridOptions = { // then refer to the component by name columnDefs: [ { field: 'country', cellRenderer: CountryCellRenderer, filter: CountryFilter }, ], ... }

Advantages of By Name

Registering components by name has the following advantages:

  • Implementations can change without having to change all the column definitions. For example, you may have 20 columns using a currency cell renderer. If you want to update the cell renderer to another currency cell renderer, you only need to do it in only place (where the cell renderer is registered) and all columns will pick up the new implementation.
  • The part of the grid specifying column definitions is plain JSON. This is helpful for applications that read column definitions from static data. If you referred to the class name directly inside the column definition, it would not be possible to convert the column definition to JSON.

Registering Framework Components

Most of the frameworks ag-Grid works with use components. It is possible to use the framework components inside of ag-Grid. Configuring the components is same and explained in this section. The frameworks that follow this conventions are:

  • Angular (version 2 and later)
  • React
  • VueJS
  • Polymer
The following frameworks are not configured in this way:
  • AngularJS 1: This framework does not follow the same pattern as other frameworks. See AngularJS on how you can turn on AngularJS 1 compiling to use AngularJS bindings inside ag-Grid.
  • Aurelia: Aurelia uses templates instead of components.

If you are using on of the supported frameworks registration is done using the frameworkComponents property rather than the components property. Then the component is registered by name as normal.

gridOptions = { // use frameworkComponents instead of components. most frameworks will allow you // to specify this as a bound property. frameworkComponents: { countryCellRenderer: AngularCountryCellRenderer, countryFilter: AngularCountryFilter }, // then refer to the component by name as before columnDefs: [ { field: 'country', cellRenderer: 'countryCellRenderer', filter: 'countryFilter' }, ], ... }

You can also refer to the component classes directly using the framework variant of the property. For example instead of using cellRenderer you use cellRendererFramework.

gridOptions = { // then refer to the component by name columnDefs: [ { field: 'country', cellRendererFramework: CountryCellRenderer, filterFramework: CountryFilter }, ], ... }

Summary of Component Registration

Here we give an overview, as there is a lot of similar sounding information above.

The grid options has the following properties for registering components:

Component Registration

components A map of component names to plain JavaScript components.
frameworkComponents A map of component names to framework (React, Angular etc) components.

Component Usage

The below table gives an overview of where components can be used. The table shows both options for usage:

  • Name / Direct JavaScript: This can be: 1) A component name referring to a registered component (either plain JavaScript or framework component); 2) A direct reference to a JavaScript component.
  • Direct Framework: A direct reference to a framework (React, Angular etc) component.

Component Where Name / Direct JavaScript Direct Framework
Detail Cell Renderer Grid Option detailCellRenderer detailCellRendererFramework
Full Width Cell Renderer Grid Option fullWidthCellRenderer fullWidthCellRendererFramework
Group Row Cell Renderer Grid Option groupRowRenderer groupRowRendererFramework
Group Row Inner Cell Renderer Grid Option groupRowInnerRenderer groupRowInnerRendererFramework
Loading Overlay Grid Option loadingOverlayRenderer loadingOverlayRendererFramework
No Rows Overlay Grid Option noRowsOverlayRenderer noRowsOverlayRendererFramework
Date Component Grid Option dateComponent dateComponentFramework
Cell Renderer Column Definition cellRenderer cellRendererFramework
Pinned Row Cell Renderer Column Definition pinnedRowCellRenderer pinnedRowCellRendererFramework
Cell Editor Column Definition cellEditor cellEditorFramework
Filter Column Definition filter filterFramework
Floating Filter Column Definition floatingFilterComponent floatingFilterComponentFramework
Header Component Column Definition headerComponent headerComponentFramework
Header Group Component Column Definition headerGroupComponent headerGroupComponentFramework

JavaScript or Framework

If you are using a framework, then you have a choice of the following:

  1. Provide an ag-Grid component in JavaScript.
  2. Provide an ag-Grid component as a framework component (eg React or Angular).
For example if you want to build a cell renderer and you are using React, you have the choice to build the cell renderer using React or using plain JavaScript.

If using a framework, you should first read how to build the component using plain JavaScript. This is because the framework specific component builds on what you learn from the JavaScript component.

Mixing JavaScript and Framework

It is possible to mix JavaScript and framework components in the same application. The following code snippet shows how such can be configured:

gridOptions = { // JavaScript components registered here components: { countryFilter: CustomCountryFilter }, // Framework components registered here frameworkComponents: { countryCellRenderer: CountryCellRenderer }, columnDefs: [ { field: 'country', // filter is a registered plain JavaScript component filter: 'countryFilter', // cell renderer is a registered framework (React, Angular etc) component cellRenderer: 'countryCellRenderer' } ] };

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.

Date Inputs
agDateInput Default date input used by filters.
Column Headers
agColumnHeader Default column header.
agColumnHeaderGroup Default column group header.
Column Filters
agSetColumnFilter Set filter (default when using ag-Grid Enterprise).
agTextColumnFilter Simple text filter (default when using ag-Grid Free).
agNumberColumnFilter Number filter.
agDateColumnFilter Date filter.
Floating Filters
agSetColumnFloatingFilter Floating set filter.
agTextColumnFloatingFilter Floating text filter.
agNumberColumnFloatingFilter Floating number filter.
agDateColumnFloatingFilter Floating date filter.
Cell Renderers
agAnimateShowChangeCellRenderer Cell renderer that animates value changes.
agAnimateSlideCellRenderer Cell renderer that animates value changes.
agGroupCellRenderer Cell renderer for displaying group information.
agLoadingCellRenderer Cell editor for loading row when using Enteprise row model.
Overlays
agLoadingOverlay Loading overlay.
agNoRowsOverlay No rows overlay.
Cell Editors
agTextCellEditor Text cell editor.
agSelectCellEditor Select cell editor.
agRichSelectCellEditor* Rich select editor.
agPopupTextCellEditor Popup text cell editor.
agPopupSelectCellEditor Popup select cell editor.
agLargeTextCellEditor Large text cell editor.
Master Detail
agDetailCellRenderer* Detail panel for master / detail grid.

* Enterprise Feature

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:

  • 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.
  • agLoadingOverlay: To change the default 'loading' overlay.
  • agNoRowsOverlay: To change the default loading 'no rows' overlay.
  • agTextCellEditor: To change the default text cell editor.
  • agDetailCellRenderer: To change the default detail panel for master / detail grids.