Ag-Grid React Overview

ag-Grid React Features

Every feature of ag-Grid is available when using the ag-Grid React Component. The React Component wraps the functionality of ag-Grid so you gain all the features of ag-Grid along with all good stuff that React provides.

Table of Contents


Configuring the ag-Grid React Component

After importing AgGridReact you can then reference the component inside your JSX definitions. An example of the Grid Component can be seen below:

// Grid Definition <AgGridReact // listening for events onGridReady={this.onGridReady} // binding to array properties rowData={this.state.rowData} // no binding, just providing hard coded strings for the properties // boolean properties will default to true if provided (ie animateRows => animateRows="true") rowSelection="multiple" animateRows // setting grid wide date component dateComponentFramework={DateComponent} // setting default column properties defaultColDef={{ headerComponentFramework: SortableHeaderComponent, headerComponentParams: { menuIcon: 'fa-bars' } }}> // column definitions <AgGridColumn field="make"></AgGridColumn> </AgGridReact>>

Configuring the Columns

Columns can be defined in three ways: declaratively (i.e. via markup), via GridOptions or by binding to columnDefs on the AgGridReact component.

In all cases all column definition properties can be defined to make up a column definition.

Defining columns declaratively:

// column definitions <AgGridColumn field="make"></AgGridColumn> <AgGridColumn field="model"></AgGridColumn> <AgGridColumn field="price"></AgGridColumn>

Defining columns via GridOptions:

// before render/grid initialisation this.state = { gridOptions = { columnDefs: [ {make: "Toyota", model: "Celica", price: 35000}, {make: "Ford", model: "Mondeo", price: 32000}, {make: "Porsche", model: "Boxter", price: 72000} ] } } // in the render method <AgGridReact gridOptions={this.state.gridOptions}></AgGridReact>

Defining columns by binding to a property:

// before render/grid initialisation this.state = { columnDefs: [ {make: "Toyota", model: "Celica", price: 35000}, {make: "Ford", model: "Mondeo", price: 32000}, {make: "Porsche", model: "Boxter", price: 72000} ] } // in the render method <AgGridReact columnDefs={this.state.columnDefs}></AgGridReact>

A full working Grid definition is shown below, illustrating various Grid & Column property definitions:

<AgGridReact // listening for events onGridReady={this.onGridReady} // binding to array properties rowData={this.state.rowData} // no binding, just providing hard coded strings for the properties // boolean properties will default to true if provided (ie animateRows => animateRows="true") rowSelection="multiple" animateRows // setting grid wide date component dateComponentFramework={DateComponent} // setting default column properties defaultColDef={{ sortable: true, filter: true, headerComponentFramework: SortableHeaderComponent, headerComponentParams: { menuIcon: 'fa-bars' } }}> <AgGridColumn headerName="#" width={30} checkboxSelection suppressMenu pinned></AgGridColumn> <AgGridColumn headerName="Employee" headerGroupComponentFramework={HeaderGroupComponent}> <AgGridColumn field="name" width={150} pinned editable cellEditorFramework={NameCellEditor}></AgGridColumn> <AgGridColumn field="country" width={150} pinned editable cellRenderer={RichGridDeclarativeExample.countryCellRenderer} filterParams={{cellRenderer: RichGridDeclarativeExample.countryCellRenderer, cellHeight:20}}></AgGridColumn> </AgGridColumn> </AgGridReact>

Access the Grid & Column API

When the grid is initialised, it will fire the gridReady event. If you want to use the API of the grid, you should put an onGridReady(params) callback onto the grid and grab the api from the params. You can then call this api at a later stage to interact with the grid (on top of the interaction that can be done by setting and changing the props).

// provide gridReady callback to the grid <AgGridReact onGridReady={this.onGridReady} .../> // in onGridReady, store the api for later use onGridReady = (params) => { this.api = params.api; this.columnApi = params.columnApi; } // use the api some point later! somePointLater() { this.api.selectAll(); this.columnApi.setColumnVisible('country', visible); }

The api and columnApi are also stored inside the React backing object of the grid. So you can also look up the backing object via React and access the api and columnApi that way.

Loading CSS

ag-Grid requires the core ag-Grid CSS as well as a theme.

import 'ag-grid-community/dist/styles/ag-grid.css'; import 'ag-grid-community/dist/styles/ag-theme-balham.css';

If you're using webpack you can configure an alias to allow for absolute imports (this isn't necessary when using create-react-app:

resolve: { alias: { "ag-grid-community": path.resolve('./node_modules/ag-grid-community')

Applying a Theme

You need to set a theme for the grid. You do this by giving the grid a CSS class, one of ag-theme-balham, ag-theme-material, ag-theme-fresh, ag-theme-blue or ag-theme-dark. You must have the CSS loaded as specified above for this to work.

// a parent container of the grid, you could put this on your body tag // if you only every wanted to use one style of grid // HTML <div class="ag-theme-balham"> ... // OR JSX <div className="ag-theme-balham"> ... // then later, use the grid <AgGridReact ...

Putting the CSS and theme all together you'll end up with something like this:

// a react component import 'ag-grid-community/dist/styles/ag-grid.css'; import 'ag-grid-community/dist/styles/ag-theme-balham.css'; class GridComponent extends Component { render() { return ( <div className="ag-theme-balham"> <AgGridReact onGridReady={this.onGridReady} rowData={this.state.rowData} ...other bindings/properties > <AgGridColumn field="athlete" width={30}></AgGridColumn> ...other column definitions </AgGridReact> ) } }

Customising the Grid with React Components

It is possible to customise the grid with React components (for example, cell renderers, cell editors and filters and so on using React. For the full list of available grid components and how to configure them please refer to the components documentation

ag-Grid with React 16+

All of the documentation in this section apply to React 16+. For documentation for React 15+ please see here.

With React 16 Portals were introduced and these are the official way to create React components dynamically within React so this is what we use internally for component creation within the grid.

If you use React 16+ you'll need to enable reatNext as follows:

// Grid Definition <AgGridReact reactNext={true} ...other bindings

In a future release we'll switch to make reactNext the default, but for now this needs to be made explicit.

Control React Components Container

By default user supplied React components will be wrapped in a div but it is possible to have your component wrapped in a container of your choice (i.e. a span etc), perhaps to override/control a third party component.

For example, assuming a user component as follows:

class CellRenderer extends Component { render() { return( Age: {props.value} ) } }

The default behaviour will render the following within the grid:

<div class="ag-react-container"><span>Hello World</span></div>

In order to override this default behaviour and can specify a componentWrappingElement:

<AgGridReact onGridReady={this.onGridReady} rowData={this.state.rowData} componentWrappingElement='span' ...other properties

Doing this would result in the following being rendered:

<span class="ag-react-container"><span>Hello World</span></span>

If you wish to override the style of this div you can either provide an implementation of the ag-react-container class, or via the reactContainer property that will be made available via props:

constructor(props) { super(props); // change the containing div to be inline-block (instead of the default block for a div) this.props.reactContainer.style.display = "inline-block"; // change the background color of the containing div to be red this.props.reactContainer.style.backgroundColor = "red"; }

You can see an example of this in the Grouped Row Example where we change the display of the groupRowInnerRendererFramework to inline-block so that the +/- and label are inline.

Functional/Stateless Components will have a wrapping container (a div by default) provided due to technical constraints.

Redux / Higher Order Components (HOC)

We provide a guide on how to use ag-Grid with Redux in our React/Redux Integration Guide

If you use connect to use Redux, or if you're using a Higher Order Component (HOC) to wrap the grid React component at all, 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 GridOptions.reactNext )(PriceRenderer);

React Context API

If you're using the new React Context API then you can access the context in the components used within the grid.

First, let's create a context we can use in our components:

import React from "react"; export default React.createContext('normal');

Next we need to provide the context in a parent component (at the Grid level, or above) - for example:

<FontContext.Provider value="bold"> <GridComponent/> </FontContext.Provider>

Finally, we need to consume the context within our component:

class StyledRenderer extends Component { render() { return ( <FontContext.Consumer> {fontWeight => <span style={{fontWeight}}>Stylised Component!</span> } </FontContext.Consumer> ); } }

React Hooks

React Hooks are fully supported as cell renderers - please refer to our working example in GitHub.

You can currently use Hooks for renderers only - support for React Hooks in Editors/Filter etc is not currently supported.

Row Data Control

By default the ag-Grid React component will check props passed in to deteremine if data has changed and will only re-render based on actual changes.

For rowData we provide an option for you to override this behaviour by the rowDataChangeDetectionStrategy property:

<AgGridReact onGridReady={this.onGridReady} rowData={this.state.rowData} rowDataChangeDetectionStrategy='IdentityCheck' ...other properties

The following table illustrates the different possible combinations:

Strategy Behaviour Notes
IdentityCheck Checks if the new prop is exactly the same as the old prop (i.e. ===) Quick, but can result in re-renders if no actual data has changed
DeepValueCheck Performs a deep value check of the old and new data Can have performance implication for larger data sets
NoCheck Does no checking - passes the new value as is down to the grid Quick, but can result in re-renders if no actual data has changed

The default value for this setting is:

DeltaRowDataMode Default
true IdentityCheck
false DeepValueCheck

If you're using Redux or larger data sets thena default of IdentityCheck is a good idea provided you ensure you make a copy of thew new row data and do not mutate the rowData passed in.

Control React Components Container

By default user supplied React components will be rendered with a div container but it is possible to have your specify a container (i.e. a div, span etc), perhaps to override/control a third party component.

For example, assuming a user component as follows:

class CellRenderer extends Component { render() { return(
Age: {props.value}
) } }

The default behaviour will render the following within the grid:

<div class="ag-react-container"><span>Age: 24</span></div>

In order to override this default behaviour and can specify a componentWrappingElement:

<AgGridReact onGridReady={this.onGridReady} rowData={this.state.rowData} componentWrappingElement='span' ...other properties

Doing this would result in the following being rendered:

<span class="ag-react-container"><span>Age: 24</span></span >

If you wish to override the style of this div you can either provide an implementation of the ag-react-container class, or via the reactContainer property that will be made available via props:

constructor(props) { super(props); // change the containing div to be inline-block (instead of the default block for a div) this.props.reactContainer.style.display = "inline-block"; // change the background color of the containing div to be red this.props.reactContainer.style.backgroundColor = "red"; }

You can see an example of this in the Grouped Row Example where we change the display of the groupRowInnerRendererFramework to inline-block so that the +/- and label are inline.

Working Examples

You can find fully working examples at our ag Grid React Example. The example demonstrates a legacy setup (without reactNext, as well as a simple Redux and Hooks examples.

React Grid Resources


  • Learn how to customize our React Grid in this guide.

  • Browse our React Grid page to discover all major benefits in using ag-Grid React.

  • Visit our blog to discover all our React content.

Next Steps

Now you can go to our react grid reference to learn about accessing all the features of the grid.