React Data GridGrid Interface
This section details the public interface that your application can use to interact with the grid, including methods, properties and events.
The grid interface is the combination of the following items:
- Grid Options: properties and callbacks used to configure the grid, e.g.
pagination = true
andgetRowHeight(params)
. - Grid API: methods used to interact with the grid after it's created, e.g.
api.getSelectedRows()
. - Grid Events: events published by the grid to inform applications of changes in state, e.g.
rowSelected
. - Row Node: each row in the grid is represented by a Row Node object, which in turn has a reference to the piece of row data provided by the application. The Row Node wraps the row data item. The Row Node has attributes, methods and events for interacting with the specific row e.g.
rowNode.setSelected(true)
.
Properties, Events, Callbacks and APIs
- Properties: properties are defined by passing React props down to AG Grid (e.g.
columnDefs={this.state.columnDefs}
) - Callbacks: callbacks are also defined using React Props (e.g.
getRowHeight={this.myGetRowHeightFunction}
). - Event Handlers: event handlers are also defined using React Props (e.g.
onCellClicked={this.onCellClicked}
). - API: The grid API and column API are provided to you via the
onGridReady()
event callback.
So in summary, in React, everything is done via props. Here is an example:
<AgGridReact
ref={gridRef} // useful for accessing the grid's API
rowSelection="multiple" // simple attributes, not bound to any state or prop
// these are bound props, so can use anything in React state or props
columnDefs={columnDefs}
showToolPanel={showToolPanel}
// this is a callback
getRowHeight={myGetRowHeightFunction}
// these are registering event callbacks
onCellClicked={onCellClicked}
onColumnResized={onColumnEvent}
// inside onGridReady, you receive the grid APIs if you want them
onGridReady={onGridReady}
/>
React Hooks
When setting properties, it's best to treat non-simple types as immutable objects (e.g. by using useState
or useMemo
). See React Hooks for best practices on using React Hooks with the grid.
Access the Grid & Column API
The API of the grid can be referenced through the component's React Reference.
// React reference
const gridRef = useRef();
const myListener = ()=> {
// api and columnApi on the gridRef object
const {api, columnApi} = gridRef.current;
// api's will be null before grid initialised
if (api==null || columnApi==null) { return; }
// access the Grid API
gridRef.api.deselectAll();
// access the Grid Column API
gridRef.columnApi.resetColumnState();
}
<button click={myListener}>Do Something</button>
<AgGridReact
ref={gridRef}
//...
/>
The Grid API and Column API are also provided as part of all the grid events as well as a parameters to all grid callbacks.
// access API from event object
onGridReady = e => {
e.api.sizeColumnsToFit();
e.columnApi.resetColumnState();
}
// access API from callback params object
sendToClipboard = params => {
params.api.sizeColumnsToFit();
params.columnApi.resetColumnState();
}
<AgGridReact
onGridReady={onGridReady} // register event listener
sendToClipboard={sendToClipboard} // register callback
//...
/>
Given React is asynchronous, the grid may not be initialised when you access the API from the
React reference. If you want to access the API as soon as it's available (ie do initialisation
work), consider listening to the gridReady
event and doing such initialisation there.
Grid Options
The gridOptions
object is a 'one stop shop' for the entire interface into the grid, commonly used if using plain JavaScript.
Grid options can however be used instead of, or in addition to, normal framework bindings. If an option is set via gridOptions
, as well as a property on the component, then the component property will take precedence.
The GridOptions interface supports a generic parameter for row data as detailed in Typescript Generics.
The example below shows the different types of items available on gridOptions
.
const gridOptions = {
// PROPERTIES
// Objects like myRowData and myColDefs would be created in your application
rowData: myRowData,
columnDefs: myColDefs,
pagination: true,
rowSelection: 'single',
// EVENTS
// Add event handlers
onRowClicked: event => console.log('A row was clicked'),
onColumnResized: event => console.log('A column was resized'),
onGridReady: event => console.log('The grid is now ready'),
// CALLBACKS
getRowHeight: (params) => 25
}
<AgGridReact
gridOptions={gridOptions}
Note the if using Grid Options, the grid will not react to property changes. For example gridOptions.rowData
will only get used once when the grid is initialised, not if you change gridOptions.rowData
after the grid is initialised. For this reason, while using React, it's best only use Grid Options for properties that do not change.
Once the grid is initialised, you will also have access to the grid API (api
) and column API (columnApi
) on the gridOptions
object as shown:
// refresh the grid
gridOptions.api.redrawRows();
// resize columns in the grid to fit the available space
gridOptions.columnApi.sizeColumnsToFit();
Events Are Asynchronous
Grid events are asynchronous so that the state of the grid will be settled by the time your event callback gets invoked.
Default Boolean Properties
Where the property is a boolean (true
or false
), then false
(or left blank) is the default value. For this reason, on / off items are presented in a way that causes the most common behaviour to be used when the value is false
. For example, suppressCellFocus
is named as such because most people will want cell focus to be enabled.
Next Steps
That's it, Doc! Now you know how to interface with the grid. Go now and find out about all the great options, methods and events you can use.