Implementing the React Datagrid

If you are building a React application then you have the choice between A) using the plain JavaScript version of ag-Grid or B) using the ag-Grid React Component from the ag-grid-react project. If you use the ag-Grid React Component, then the grid's properties, events and API will all tie in with the React ecosystem. This will make your React coding easier.

You will also have the option (but not forced) of using React Components internally in the grid for rendering, editing and filtering. The example has to applications as follows:

  • Standard - the standard is shown below and demonstrates using React Components for renderers, editors and filters.
  • Large - the large uses only one simple React Component for rendering the entire grid and the grid has many rows and columns and fills the entire web page. This project is proof of concept that ag-Grid can manage large data when using React to render. If you are having performance issues in your React application, it's not because of ag-Grid.

Example ag-Grid and React

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, it doesn't duplicate, so there will be no difference between core ag-Grid and React ag-Grid when it comes to features.

Dependencies

Using ReactJS with ag-Grid introduces a dependency on React. For this reason:

  • You need to include the additional project ag-grid-react, which has the React dependency.
  • You cannot use the bundled version of ag-Grid. You must use the CommonJS distribution.

In your package.json file, specify dependency on ag-grid AND ag-grid-react. The ag-grid package contains the core ag-grid engine and the ag-grid-react contains the React component and some utils for React rendering.

"dependencies": {
    // ag-Grid and ag-Grid React projects
    "ag-grid": "8.0.x",
    "ag-grid-react": "8.0.x",

    // include this if using ag-Grid Enterprise
    "ag-grid-enterprise": "8.0.x"
}
The major and minor versions should match. Every time a new major or minor version of ag-Grid is released, the component will also be released. However for patch versions, the component will not be released.

Configuring AgGridReact Component

The root of the example application is MyApp.jsx. At the top of this file you can see the import the AgGridReact component as follows:

import {AgGridReact} from 'ag-grid-react';
After the import you can then reference the component inside your JSX definitions. See the render() function in MyApp.jsx, it has AgGridReact defined as follows (Make sure that you set the height for the parent element of ``):
<AgGridReact

    // listen for events with React callbacks
    onRowSelected={this.onRowSelected.bind(this)}
    onCellClicked={this.onCellClicked.bind(this)}

    // binding to properties within React State or Props
    showToolPanel={this.state.showToolPanel}
    quickFilterText={this.state.quickFilterText}
    icons={this.state.icons}

    // column definitions and row data are immutable, the grid
    // will update when these lists change
    columnDefs={this.state.columnDefs}
    rowData={this.state.rowData}

    // or provide props the old way with no binding
    rowSelection="multiple"
    enableSorting="true"
    enableFilter="true"
    rowHeight="22"
/>

Loading CSS

You need 1) the core ag-Grid css and 2) a theme. These are stored in css files packaged in the core ag-Grid. To access them, first up we need to define an alias to use inside webpack.config.js:

alias: {
    "ag-grid-root" : __dirname + "/node_modules/ag-grid"
}
Once this is done, we can then access the two css files that we need as follows:
import 'ag-grid-root/dist/styles/ag-grid.css';
import 'ag-grid-root/dist/styles/theme-fresh.css';
You will also need to configure CSS loaders for Webpack.

Applying Theme

You need to set a theme for the grid. You do this by giving the grid a CSS class, one of ag-fresh, ag-blue or ag-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-fresh">
    ...

// OR JSX
<div className="ag-fresh">
    ...

    // then later, use the grid
    <AgGridReact
        ...

Grid 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.bind(this)}
    .../>

// 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.

Next Steps

The above is all you need to get started using ag-Grid in a React application. Now would be a good time to try it in a simple app and get some data displaying and practice with some of the grid settings before moving onto the advanced features of cellRendering and custom filtering.

Cell Rendering, Cell Editing and Filtering using React

It is possible to build cellRenderers, cellEditors and filters using React. Doing each of these is explained in the section on each.

Although it is possible to use React for your customisations of ag-Grid, it is not necessary. The grid will happily work with both React and non-React portions (eg cellRenderers in React or normal JavaScript). If you do use React, be aware that you are adding an extra layer of indirection into ag-Grid. ag-Grid's internal framework is already highly tuned to work incredibly fast and does not require React or anything else to make it faster. If you are looking for a lightning fast grid, even if you are using React and the ag-grid-react component, consider using plain ag-Grid Components (as explained on the pages for rendering etc) inside ag-Grid instead of creating React counterparts.