DataGrid - Getting started

Getting started

There are 2 editions of the <ReactDataGrid /> that you can use:
  • the Community Edition - includes the core grid functionality most people actually use in their products - you can install it by doing
    $ npm install @inovua/reactdatagrid-community --save
  • the Enterprise Edition - includes advanced functionality, especially targeted for enterprise apps
    $ npm install @inovua/reactdatagrid-enterprise --save
Both editions of the <ReactDataGrid /> are published and available in the public npm registry.

Evaluating and using the Enterprise Edition

The Enterprise Edition is a commercial product and requires a license - please visit the pricing page for more details. Once you purchase a license, we'll provide you a license key, so you can start using <ReactDataGrid /> in your apps.
You are free to evaluate the Enterprise Edition of <ReactDataGrid /> even without a license key - all features are available and ready to use, but a license notice will be displayed initially for a few seconds. If you want to remove that, you can contact us and we'll send you an evaluation license key which you can use for 30 days.
Please note you are not allowed to integrate the Enterprise Edition of the <ReactDataGrid /> into end products or use it for any commercial, productive or training purpose without a valid commercial license. Read EULA for more details.
After you purchase and receive your commercial license key, you have to set it in the licenseKey prop then you can start using the <ReactDataGrid /> in development and production.
import ReactDataGrid from '@inovua/reactdatagrid-enterprise'
import '@inovua/reactdatagrid-enterprise/index.css'

<ReactDataGrid
  licenseKey="..."
/>
The Enterprise Edition features are listed in the left navigation menu with the
e
sign.
Even without a license key, all features are unlocked so you can evaluate the <ReactDataGrid /> and decide whether you need the Community or the Enterprise Edition.

Using the component

For ease of use, this documentation site only uses the Enterprise Edition of <ReactDataGrid />.
We have an extensive API page, which you will find useful.
The <ReactDataGrid /> ships with multiple themes out-of-the-box, but the "default-dark" theme is used in this documentation. In order to use the default light theme, specify theme="default-light". See the section about theming below to find out more.
To start using the <ReactDataGrid /> component, all you need to import is React and the code + styles of the component itself: @inovua/reactdatagrid-enterprise and @inovua/reactdatagrid-enterprise/index.css.
This is the most basic setup for a <ReactDataGrid />. In the next sections and pages we'll explore how to use the <ReactDataGrid /> in various scenarios, supported props, functionality, theming, etc.
To boost performance of the <ReactDataGrid />, we treat props as immutable and only update the <ReactDataGrid /> when you pass different props.
For example, to improve the rendering performance, make sure you pass the same reference to a columns array when rendering the grid, instead of building the columns array in the render function of your app and passing it new each time to the grid, even when the columns don't change.
As another consequence of virtualization, by default the height of rows in the <ReactDataGrid /> is fixed, as configured by rowHeight, which defaults to rowHeight=40.

Defining columns

Columns are fundamental to grids, so defining them is rather easy - pass an array of objects with name property. A column should either have a name or an id property. If the id is specified, it should be unique. If a column only specifies the name property, it should also be unique.
The simplest dataSource is an array of objects, with properties matching the names of the grid columns (the name property). Objects in the dataSource can contain any other properties, and will generally contain an identifier property - most of the times named id (which is also the default value). This identifier property name should be used as the idProperty to help uniquely identify grid rows.
Adding a header (can be any valid React.Node) property to columns renders the corresponding value in the header of the respective column.
Passing a difference instance of the columns at each render will slow down the rendering performance of the <ReactDataGrid />.
Columns support custom rendering, and don't need to match a corresponding property in the dataSource items. This can be achieved by using the column.render function, as illustrated in the example below.
Columns support fixed or flexible sizing. Specifying a fixed size can be done by configuring a column.defaultWidth (or the controlled column.width) . A flexible column needs to have column.defaultFlex (or the controlled column.flex) set to a valid numeric value - it's using flexbox layout to determine the dimension of the flexible column (subtracts the total fixed column widths from the total available space, then divide this by the sum of all flexes and multiply that value with the flex value of each flexible column). Additionally, column.minWidth and column.maxWidth can be configured for both fixed and flexible columns to ensure some minimum or maximum dimensions are always respected.
column.width is a controlled prop, so when the user resizes the column, you have to make sure you listen to onColumnResize and update the column width accordingly.
As such, you may want to use the uncontrolled column.defaultWidth to specify the column size for a fixed column, so it updates the column width on resize without any other configuration.
For flexible columns, it's important to consider & understand how shareSpaceOnResize works (defaults to false). .
When the <ReactDataGrid /> has flexible columns, and shareSpaceOnResize=false, when a column is resized (eg: made smaller), the flexible columns keep their current size and don't grow to fill the newly available space. However, they do keep their proportional size to all other flexible columns. Also, when the <ReactDataGrid /> has more available space, they do resize to keep the same empty space in the <ReactDataGrid />.
When the <ReactDataGrid /> is configured with shareSpaceOnResize=true, and a column is resized, flexible columns are resized to fill all available space to ensure that columns always fill the <ReactDataGrid /> viewport horizontally.
See shareSpaceOnResize for an example.
By default, columns are resizable. Specifying resizable=false makes all <ReactDataGrid /> columns unresizable.
Besides making all columns resizable/unresizable, the resizable prop can be controlled at column level. Specify column.resizable=false to make a certain column unresizable by the user or column.resizable=true to specifically enable user resizing on a certain column.
When the user drags & drops the column resize handle, the onColumnResize callback prop is called to notify the column size update. The width of the column resize handle is configurable via columnResizeHandleWidth.

Custom rendering

Columns configured with a name prop by default render the value in the corresponding property in the dataSource items.
Custom rendering (for all columns, either with a name or an id) is supported via the column.render function prop. The column.render is passed an object with the following properties:
  • value - if the column has a name, the value would be the value rendered if no column.render property were configured.
  • data - the data object in the dataSource corresponding to the current row being rendered.
  • cellProps: Object - the props being passed to the cell corresponding to the current row and column.
  • rowIndex: Number - the index of the current row being rendered.
  • rowSelected: Boolean - a boolean value indicating if the current row is selected or not.
  • rowActive: Boolean - a boolean value indicating if the current row is keyboard active or not.
  • cellSelected: Boolean - a boolean value indicating if the current cell is selected or not.
  • empty: Boolean - a boolean value indicating if the current row is an empty row or not. See showEmptyRows for details.
  • totalDataCount: Number - the total count of rows that will be rendered.
The object passed to the column.render function is reused - so you should not keep a reference to it. Instead, use ES6 destructuring to take the values you are interested in from this object.
const columns = [
  {
    name: 'firstName',
    header: 'First Name',
    defaultFlex: 1,
    header: 'First Name'
  },
  {
    name: 'lastName',
    header: 'Last Name',
    defaultFlex: 1,
    header: 'Last Name'
  },
  {
    name: 'country',
    header: 'Country',
    defaultWidth: 60,
    resizable: false,
    render: ({ value }) => flags[value] ? flags[value] : 'unknown'
  },
  {
    id: 'fullName',
    header: 'Full Name',
    minWidth: 100,
    defaultFlex: 1,
    render: ({ data }) => data.firstName + ' ' + data.lastName
  },
  {
    name: 'age',
    header: 'Age',
    render: ({ value }) => <span
      style={{ color: value < 30 ? 'lightgreen' : 'inherit'}}
    >{value}</span>
  }
]
The <ReactDataGrid /> column cells are optimized to only render when there is a change in the underlying dataSource, therefore, the column.render function should be pure. If not pure, and if the column.render uses variables defined outside of the function, make sure you specify columns.shouldComponentUpdate to return true.
By default, if columns don't specify a header, the column.name is used (after it's upper-cased and humanized) as the column header.
By adding a column.header prop (any valid React.Node or even a function) you can have full control over what gets rendered as the column header - even for different states of the column (sorted, filtered, etc).
In the example above, the first column uses custom header rendering, while the second column turns off sorting by adding column.sortable=false. The third column uses custom cell rendering, via the column.render function.

Using a data source

The dataSource prop specifies the source of data for grid contents. The <ReactDataGrid /> supports both sync & async dataSource.
The simplest use-case is a synchronous dataSource, in the form of an array. The dataSource items (the objects in the array) are not constrained to a specific shape, but they need to have a property which can be used as a unique identifier (most often, this is called "id"). When configuring the <ReactDataGrid />, this property should be specified in the idProperty="id". The properties in the dataSource items, although not constrained to a certain shape, will generally match the configured columns.
To boost performance of the <ReactDataGrid />, we treat props as immutable and only update the <ReactDataGrid /> when you pass different props.
So for example, to improve the rendering performance, make sure you pass the same reference to a dataSource when rendering the grid, instead of building the dataSource in the render function of your app and passing it new each time to the grid, even when the dataSource doesn't change.
Passing the same dataSource on each render when it doesn't change is especially important in some cases when the <ReactDataGrid /> indexes your dataSource array or performs other performance-sensitive tasks.

Using async or remote data

Besides a plain array, the <ReactDataGrid /> supports async dataSource which can be specified as a Promise or a function returning a Promise. Again, the rules of immutability apply, so make sure you pass a reference to the same Promise/function when you want to render the same-exact dataSource.
The promise (as specified by dataSource or as returned by the dataSource function) should be resolved with two possible value types:
  • an array - to be used as the data for the grid
  • an object with the data: Array and count: Number properties - this is generally useful when using remote data with pagination and the count represents the total number of records on the server (only a part of those are sent to the client via pagination).
Besides returning a Promise, dataSource as a function can also return an array, for synchronous dataSource that you want to have full control over (this function is called with information about sortInfo, and limit).
By default, when an async dataSource is used, a <LoadMask is displayed while the promise is unresolved, and hidden once the promise is resolved. However, you can also use the controlled loading prop to have full control over when the grid shows the loading mask.
TIP: You can also use onLoadingChange to know when the <LoadMask is being shown or hidden.
For details on using pagination with the dataSource, see the pagination page.
When there is no data available in the <ReactDataGrid />, a message indicating that no records are available is shown, as specified by emptyText.

Getting a handle or a ref to the grid

If you ever need to get e reference to the <ReactDataGrid /> instance (you should only need this in very advanced cases) - you can add a onReady function prop, to get a reference to the computed props of the grid, which holds all the required info for grid rendering. For example, seeclearAllFilters method usage for an example on usage.

Theming

The <ReactDataGrid /> supports a theme prop, which by default has the value of "default-light".
In order for the default theme to be applied you have to import @inovua/reactdatagrid-enterprise/index.css into your app:
import '@inovua/reactdatagrid-enterprise/index.css'
This file contains both the structural styles that are needed for the <ReactDataGrid /> , as well as the default (light) theme.
In case you only want to load the structural styles for the <ReactDataGrid />, you can import @inovua/reactdatagrid-enterprise/base.css instead.
import '@inovua/reactdatagrid-enterprise/base.css'
Be aware, though, that in this case you'll have to style the <ReactDataGrid /> appearance from scratch.
However, you can import both the structural styles and the default theme separately:
import '@inovua/reactdatagrid-enterprise/base.css'
import '@inovua/reactdatagrid-enterprise/theme/default-light.css'
Here's a list of available thems:
  • "amber-light"
  • "amber-dark"
  • "blue-light"
  • "blue-dark"
  • "default-light"
  • "default-dark"
  • "green-light"
  • "green-dark"
  • "pink-light"
  • "pink-dark"
In order to use any of the above, you have to import @inovua/reactdatagrid-enterprise/theme/<THEME_NAME>.css. Also make sure you import @inovua/reactdatagrid-enterprise/base.css (or @inovua/reactdatagrid-community/base.css). The base.css file is included with @inovua/reactdatagrid-enterprise/index.css, which contains @inovua/reactdatagrid-enterprise/base.css AND the default theme, @inovua/reactdatagrid-enterprise/theme/default-light.css.
To read more about specifically theming <ReactDataGrid /> components, go ahead to the section on DataGrid styling and theming.

Browser support

We fully support the last 2 major versions of every modern browser.
Although we support only recent browser versions, we've tried to offer our users extensive market reach and as such ReactDataGrid is running well even in IE11 - though we expect the experience on IE11 to degrade soon as we adopt newer technologies that are only present in the latest browser versions, as IE11 is not officially supported by our team.

React support

The minimum React version we support is 16.8.0 - it's the version that adds support for React hooks.
We started developing the ReactDataGrid before hooks came out and before some React lifecycle methods have been deprecated. After React 16.8.0 was released we decided it was worth migrating to hooks to simplify our code and be able to better share logic internally. It was around that time that we decided to pivot to TypeScript and give ourselves and our users the confidence of types and better intellisense.
Though the transition to hooks was successful, there are a few places that still need upgrading - and we expect that to happen as we consolidate our codebase going further.
Top