Data grid advanced

Ref methods

For advanced use cases, and particularly for data grids that manage associated modals/flyouts and need to manually control their grid cell popovers & focus states, we expose certain internal methods via the ref prop of EuiDataGrid. These methods are:

setIsFullScreen(isFullScreen) - controls the fullscreen state of the data grid. Accepts a true/false boolean flag.
setFocusedCell({ rowIndex, colIndex }) - focuses the specified cell in the grid.
- Using this method is an accessibility requirement if your data grid toggles a modal or flyout. Your modal or flyout should restore focus into the grid on close to prevent keyboard or screen reader users from being stranded.
openCellPopover({ rowIndex, colIndex }) - opens the specified cell's popover contents.
closeCellPopover() - closes any currently open cell popover.

Handling cell location

When using setFocusedCell or openCellPopover, keep in mind:

colIndex is affected by the user reordering or hiding columns.
If the passed cell indices are outside the data grid's total row count or visible column count, an error will be thrown.
If the data grid is paginated or sorted, the grid will handle automatically finding specified row index's correct location for you.

react-window methods

EuiDataGrid also exposes several underlying methods from react-window's VariableSizeGrid imperative API via its ref:

scrollTo({ scrollLeft: number, scrollTop: number }) - scrolls the grid to the specified horizontal and vertical pixel offsets.
scrollToItem({ align: string = "auto", columnIndex?: number, rowIndex?: number }) - scrolls the grid to the specified row and columns indices

react-window vs. EUI

Unlike EUI's ref APIs, rowIndex here refers to the visible rowIndex when passed to a method of a native react-window API.

For example: scrollToItem({ rowIndex: 50, columnIndex: 0 }) will always scroll to 51st visible row on the currently visible page, regardless of the content in the cell. In contrast, setFocusedCell({ rowIndex: 50, colIndex: 0 }) will scroll to the 51st row in your data, which may not be the 51st visible row in the grid if it is paginated or sorted.

The below example shows how to use the internal APIs for a data grid that opens a modal via cell actions, that scroll to specific cells, and that can be put into full-screen mode.

Data grid in-memory

What is the difference in the examples?

These examples show the same grid built with the four available inMemory settings. While they may look the same, look at the source to see how they require different levels of data management in regards to sorting and pagination.

The grid has levels of in-memory settings that can be set. It is in the consuming application's best interest to put as much of the data grid in memory as performance allows. Try to use the highest level inMemory="sorting" whenever possible. The following values are available.

undefined (default): When not in use the grid will not autodetect schemas. The sorting and pagination is the responsibility of the consuming application.
enhancements: Provides no in-memory operations. If set, the grid will try to autodetect schemas only based on the content currently available (the current page of data).
pagination: Schema detection works as above and pagination is performed in-memory. The pagination callbacks are still triggered on user interactions, but the row updates are performed by the grid.
sorting (suggested): Schema detection and pagination are performed as above, and sorting is applied in-memory too. The onSort callback is still called and the application must own the column sort state, but data sorting is done by the grid based on the defined and/or detected schemas.

When enabled, in-memory renders cell data off-screen and uses those values to detect schemas and perform sorting. This detaches the user experience from the raw data; the data grid never has access to the backing data, only what is returned by renderCellValue.

When in-memory is not used

When inMemory is not in use the grid will not autodetect schemas. In the below example only the amount column has a schema because it is manually set. Sorting and pagination data management is the responsibility of the consuming application. Column sorting in particular is going to be imprecise because there is no backend service to call, and data grid instead defaults to naively applying JavaScript's default array sort which doesn't work well with numeric data and doesn't sort React elements such as the links. This is a good example of what happens when you don't utilize schemas for complex data.

Enhancements only in-memory

With inMemory={{ level: 'enhancements' }} the grid will now autodetect schemas based on the content it has available on the currently viewed page. Notice that the field list under Sort fields has detected the type of data each column contains.

Pagination only in-memory

With inMemory={{ level: 'pagination' }} the grid will now take care of managing the data cleanup for pagination. Like before it will autodetect schemas when possible.

Sorting and pagination in-memory

With inMemory={{ level: 'sorting' }} the grid will now take care of managing the data cleanup for sorting as well as pagination. Like before it will autodetect schemas when possible.

Custom body renderer

For extremely advanced use cases, the renderCustomGridBody prop may be used to take complete control over rendering the grid body. This may be useful for scenarios where the default virtualized rendering is not desired, or where custom row layouts (e.g., the conditional row details cell below) are required.

Please note that this prop is meant to be an escape hatch, and should only be used if you know exactly what you are doing. Once a custom renderer is used, you are in charge of ensuring the grid has all the correct semantic and aria labels required by the data grid spec, and that keyboard focus and navigation still work in an accessible manner.