React Grid | Get Started with ag-Grid and React

ag-Grid is the industry standard for React Enterprise Applications. Developers using ag-Grid are building applications that would not be possible if ag-Grid did not exist.

Please refer to our Compatibility Chart for Supported Versions of React & ag-Grid.
Quick Look Code Example
import React, { useState } from 'react'; import { render } from 'react-dom'; import { AgGridColumn, AgGridReact } from 'ag-grid-react'; import 'ag-grid-enterprise'; import 'ag-grid-community/dist/styles/ag-grid.css'; import 'ag-grid-community/dist/styles/ag-theme-alpine.css'; const App = () => { const [gridApi, setGridApi] = useState(null); const [gridColumnApi, setGridColumnApi] = useState(null); const [rowData, setRowData] = useState([ {make: "Toyota", model: "Celica", price: 35000}, {make: "Ford", model: "Mondeo", price: 32000}, {make: "Porsche", model: "Boxter", price: 72000} ]); function onGridReady(params) { setGridApi(params.api); setGridColumnApi(params.columnApi); } return ( <div className="ag-theme-alpine" style={ { height: 400, width: 600 } }> <AgGridReact onGridReady={onGridReady} rowData={rowData}> <AgGridColumn field="make"></AgGridColumn> <AgGridColumn field="model"></AgGridColumn> <AgGridColumn field="price"></AgGridColumn> </AgGridReact> </div> ); }; render(<App />, document.getElementById('root'));
<div id="root"></div>

Getting Started

In this article, we will walk you through the necessary steps to add ag-Grid (both Community and Enterprise are covered) to an existing React project, and configure some of the essential features of it. We will show you some of the fundamentals of the grid (passing properties, using the API, etc). As a bonus, we will also tweak the grid's visual appearance using Sass variables.

Thinkster has provided a free course Learning ag-Grid with React

Add ag-Grid to Your Project

For the purposes of this tutorial, we are going to scaffold a react app with create-react-app. Don't worry if your project has a different configuration. ag-Grid and the React wrapper are distributed as NPM packages, which should work with any common React project module bundler setup. Let's follow the create-react-app instructions - run the following commands in your terminal:

npx create-react-app my-app cd my-app npm start
npx comes with npm 5.2+ and higher, see instructions for older npm versions

If everything goes well, npm start has started the web server and conveniently opened a browser pointing to localhost:3000.

As a next step, let's add the ag-Grid NPM packages. run the following command in my-app (you may need a new instance of the terminal):

npm install --save ag-grid-community ag-grid-react

After a few seconds of waiting, you should be good to go. Let's get to the actual coding! Open src/App.js in your favorite text editor and change its contents to the following:

import React, { useState } from 'react'; import { AgGridColumn, AgGridReact } from 'ag-grid-react'; import 'ag-grid-community/dist/styles/ag-grid.css'; import 'ag-grid-community/dist/styles/ag-theme-alpine.css'; const App = () => { const [gridApi, setGridApi] = useState(null); const [gridColumnApi, setGridColumnApi] = useState(null); const [rowData, setRowData] = useState([ {make: "Toyota", model: "Celica", price: 35000}, {make: "Ford", model: "Mondeo", price: 32000}, {make: "Porsche", model: "Boxter", price: 72000} ]); return ( <div className="ag-theme-alpine" style={ { height: 400, width: 600 } }> <AgGridReact rowData={rowData}> <AgGridColumn field="make"></AgGridColumn> <AgGridColumn field="model"></AgGridColumn> <AgGridColumn field="price"></AgGridColumn> </AgGridReact> </div> ); }; export default App;

Done? If everything is correct, we should see a simple grid that looks like this:

ag-Grid in its simplest form

Let's go over the App.jsx changes we made:

import { AgGridColumn, AgGridReact } from 'ag-grid-react'; import 'ag-grid-community/dist/styles/ag-grid.css'; import 'ag-grid-community/dist/styles/ag-theme-alpine.css';

The three lines above import the AgGridReact and AgGridColumn components, the grid "structure" stylesheet (ag-grid.css), and one of the available grid themes: (ag-theme-alpine.css).

The grid ships several different themes; pick one that matches your project design. You can customise it further with Sass variables, a technique which we will cover further down the road.

const [rowData, setRowData] = useState([ {make: "Toyota", model: "Celica", price: 35000}, {make: "Ford", model: "Mondeo", price: 32000}, {make: "Porsche", model: "Boxter", price: 72000} ]); ... <AgGridReact rowData={rowData}> <AgGridColumn field="make"></AgGridColumn> <AgGridColumn field="model"></AgGridColumn> <AgGridColumn field="price"></AgGridColumn> </AgGridReact>

The code above presents two essential configuration properties of the grid - the column definitions (AgGridColumn) and the data (rowData). In our case, the column definitions contain three columns; each column entry specifies the header label and the data field to be displayed in the body of the table.

The actual data is defined in the rowData as an array of objects. Notice that the fields of the objects match the field values in the AgGridColumn configuration objects.

<div className="ag-theme-alpine" style={ { height: 400, width: 600 } }> <AgGridReact rowData={rowData}> <AgGridColumn field="make"></AgGridColumn> <AgGridColumn field="model"></AgGridColumn> <AgGridColumn field="price"></AgGridColumn> </AgGridReact> </div>

Finally, the JSX code above describes a wrapper DIV element which sets the grid dimensions and specifies the grid's theme by setting the className to ag-theme-alpine. As you may have already noticed, the CSS class matches the name of CSS file we imported earlier.

Enable Sorting And Filtering

So far, so good. But wouldn't it be nice to be able to sort the data to help us see which car is the least/most expensive? Well, enabling sorting in ag-Grid is actually quite simple - all you need to do is set the sort property on the column definitions.

<AgGridColumn field="make" sortable={true} ></AgGridColumn> <AgGridColumn field="model" sortable={true} ></AgGridColumn> <AgGridColumn field="price" sortable={true} ></AgGridColumn>

After adding the property, you should be able to sort the grid by clicking on the column headers. Clicking on a header toggles through ascending, descending and no-sort.

Our application doesn't have too many rows, so it's fairly easy to find data. But it's easy to imagine how a real-world application may have hundreds (or even hundreds of thousands!) of rows, with many columns. In a data set like this filtering is your friend.

As with sorting, enabling filtering is as easy as setting the filter property:

<AgGridColumn field="make" sortable={true} filter={true} ></AgGridColumn> <AgGridColumn field="model" sortable={true} filter={true} ></AgGridColumn> <AgGridColumn field="price" sortable={true} filter={true} ></AgGridColumn>

With this property set, the grid will display a small column menu icon when you hover the header. Pressing it will display a popup with a filtering UI which lets you choose the kind of filter and the text that you want to filter by.

ag-Grid sorting and filtering

Fetch Remote Data

Displaying hard-coded data in JavaScript is not going to get us very far. In the real world, most of the time, we are dealing with data that resides on a remote server. Thanks to React, implementing this is actually quite simple. Notice that the actual data fetching is performed outside of the grid component - We are using the HTML5 fetch API.

- const [rowData, setRowData] = useState([ - {make: "Toyota", model: "Celica", price: 35000}, - {make: "Ford", model: "Mondeo", price: 32000}, - {make: "Porsche", model: "Boxter", price: 72000} - ]); + const [rowData, setRowData] = useState([]); + useEffect(() => { + fetch('') + .then(result => result.json()) + .then(rowData => setRowData(rowData)) + }, []); +

Here, we replaced the rowData assignment in the constructor with a data fetch from a remote service. The remote data is the same as the one we initially had, so you should not notice any actual changes to the grid.

Enable Selection

Being a programmer is a hectic job. Just when we thought that we are done with our assignment, the manager shows up with a fresh set of requirements! It turned out that we need to allow the user to select certain rows from the grid and to mark them as flagged in the system. We will leave the flag toggle state and persistence to the backend team. On our side, we should enable the selection and, afterwards, to obtain the selected records and pass them with an API call to a remote service endpoint.

Fortunately, the above task is quite simple with ag-Grid. As you may have already guessed, it is just a matter of adding and changing couple of properties:

-<AgGridColumn field="make" sortable={true} filter={true} ></AgGridColumn> +<AgGridColumn field="make" sortable={true} filter={true} checkboxSelection={true} ></AgGridColumn> <AgGridReact + rowSelection="multiple"

Great! Now the first column contains a checkbox that, when clicked, selects the row. The only thing we have to add is a button that gets the selected data and sends it to the server. To do this, we need the following change:

<div className="ag-theme-alpine" style={ { height: 400, width: 600 } }> <button onClick={onButtonClick}>Get selected rows</button> <AgGridReact rowData={rowData} rowSelection="multiple"> <AgGridColumn field="make" sortable={true} filter={true} checkboxSelection={true} ></AgGridColumn> <AgGridColumn field="model" sortable={true} filter={true} ></AgGridColumn> <AgGridColumn field="price" sortable={true} filter={true} ></AgGridColumn> </AgGridReact> </div>

Afterwards, add the following event handler at the end of the component class:

const onButtonClick = e => { const selectedNodes = gridApi.getSelectedNodes() const selectedData = node => ) const selectedDataStringPresentation = node => node.make + ' ' + node.model).join(', ') alert(`Selected nodes: ${selectedDataStringPresentation}`) }

Well, we cheated a bit. Calling alert is not exactly a call to our backend. Hopefully you will forgive us this shortcut for the sake of keeping the article short and simple. Of course, you can substitute that bit with a real-world application logic after you are done with the tutorial.

What happened above? Several things:

  • onGridReady={ params => setGridApi(params.api) } obtained a reference to the ag-grid API instance;
  • We added a button with an event handler;
  • Inside the event handler, we accessed the grid api object reference to access the currently selected grid row nodes;
  • Afterwards, we extracted the row nodes' underlying data items and converted them to a string suitable to be presented to the user in an alert box.

Grouping (enterprise)

Grouping is a feature exclusive to ag-Grid Enterprise. You are free to trial ag-Grid Enterprise to see what you think. You only need to get in touch if you want to start using ag-Grid Enterprise in a project intended for production.

In addition to filtering and sorting, grouping is another effective way for the user to make sense out of large amounts of data.

Our current data set is pretty small so let's switch to a larger one:

- fetch('') + fetch('')

Let's enable the enterprise features of ag-grid. Install the additional package:

npm install --save ag-grid-enterprise Then, add the import to your file: import { AgGridColumn, AgGridReact } from 'ag-grid-react'; + import 'ag-grid-enterprise'; import 'ag-grid-community/dist/styles/ag-grid.css'; import 'ag-grid-community/dist/styles/ag-theme-alpine.css';

If everything is ok, you should see a message in the console that tells you there is no enterprise license key. You can ignore the message as we are trialing. In addition to that, the grid got a few UI improvements - a custom context menu and fancier column menu popup - feel free to look around:

ag-Grid final

Now, let's enable grouping! Update the AgGridReact configuration to this:

<div className="ag-theme-alpine" style={ { height: 400, width: 600 } }> <button onClick={onButtonClick}>Get selected rows</button> <AgGridReact onGridReady={onGridReady} rowData={rowData} rowSelection="multiple" + groupSelectsChildren={true} + autoGroupColumnDef={{ + headerName: "Model", + field: "model", + cellRenderer:'agGroupCellRenderer', + cellRendererParams: { + checkbox: true + } + }} - <AgGridColumn field="make" sortable={true} filter={true} checkboxSelection={true} ></AgGridColumn> + <AgGridColumn field="make" sortable={true} filter={true} checkboxSelection={true} rowGroup={true} ></AgGridColumn>

Here we've updated the component definition and set the autoGroupColumnDef and groupSelectsChildren properties.

There we go! The grid now groups the data by make, while listing the model field value when expanded. Notice that grouping works with checkboxes as well - the groupSelectsChildren property adds a group-level checkbox that selects/deselects all items in the group.

Don't worry if this step feels a bit overwhelming - the grouping feature is very powerful and supports complex interaction scenarios which you might not need initially. The grouping documentation section contains plenty of real-world runnable examples that can get you started for your particular case.

Customise the Theme Look

The last thing which we are going to do is to change the grid look and feel by customising a theme.

By default, ag-Grid ships a set of pre-built theme stylesheets. If we want to tweak the colors and the fonts of theme, we should add a Sass preprocessor to our project, override the theme variable values, and refer the ag-grid Sass files instead of the pre-built stylesheets so that the variable overrides are applied.

Adding Sass Preprocessor to create-react-app is well documented - follow the steps outlined in the respective help section.

After you are done with the setup, assuming that you have renamed src/App.css to src/App.scss, you can replace its contents with this:

@import "../node_modules/ag-grid-community/src/styles/ag-grid.scss"; @import "../node_modules/ag-grid-community/src/styles/ag-theme-alpine/sass/ag-theme-alpine-mixin.scss"; .ag-theme-alpine { @include ag-theme-alpine(( odd-row-background-color: #BFC8DC )); }

To avoid importing the stylesheets twice, remove the imports from src/App.js:

import { AgGridColumn, AgGridReact } from 'ag-grid-react'; -import 'ag-grid-community/dist/styles/ag-grid.css'; -import 'ag-grid-community/dist/styles/ag-theme-alpine.css';

If everything is configured correctly, the second row of the grid will be blue. Congratulations! You now know now bend the grid look to your will - there are a few dozens more theme parameters variables that let you control the font family and size, border color, header background color and even the amount of spacing in the cells and columns. The full list of theme parameters is available in the themes documentation section.

ag-Grid & React Compatibility Chart

React Version ag-Grid Versions
15.x 18 - 21.2.0
16.3+ 22+


With this tutorial, we managed to accomplish a lot. Starting from the humble beginnings of a three row / column setup, we now have a grid that supports sorting, filtering, binding to remote data, selection and even grouping! While doing so, we learned how to configure the grid, how to access its API object, and how to change the styling of the component.