Data grid cells & popovers

Data grid cells are rendered using the renderCellValue prop. This prop accepts a function which is treated as a React component behind the scenes. This means the data grid passes cell-specific props (e.g. row index, column/schema info, etc.) to your render function, which can ouput anything from a string to any JSX element.

Each data grid cell will automatically render an expand action button and an expansion popover (which can be disabled). For cells with overflowing or truncated content, this expansion popover helps display the full amount of content, or can be customized to show extra details.

Cell actions

In addition to making a cell expandable, you can add more custom actions by setting columns.cellActions. These actions will render as icon buttons in the cell on hover/focus, and render as full buttons in the cell expansion popover. Note that once any cellActions are passed, the cell becomes automatically expandable - this ensures keyboard and screen reader users have access to all cell actions.

columns.cellActions accepts an array of render functions. Behind the scenes, the functions are treated as a React components allowing hooks, context, and other React concepts to be used. Because different button types are used between the cell and the cell popover, we pass your render function a Component prop which you must render in order for your cell actions to switch correctly between button icons and buttons.

To close a cell's expansion popover upon clicking an action, use the closeCellPopover API available via the ref prop.

In the below example, the email and city columns provide 1 cellAction each, while the country column provides 2 cellActions.

Visible cell actions and cell popovers

By default, only the first 2 cell actions of a cell will be displayed to the left of the expand action button, and remaining actions will be displayed in the footer of the cell expansion popover.

This number is configurable by setting columns.visibleCellActions, should you need to display more cell actions immediately. However, we advise caution when increasing this limit - the default is set to ensure cell action buttons do not crowd out content.

The below example shows an increasing number of cellActions in each column. The third column shows visibleCellActions set to 3, and the fourth column shows excess actions overflowing into the popover.

Cell popover content values can be conditionally customized using the isDetails flag passed to renderCellValue. If you need basic customization of cell popover values based on, e.g. schema or column, this is the most straightforward approach.

By default, all cell popover contents are rendered with an EuiText wrapper, and cell actions are rendered within an EuiPopoverFooter as EuiEmptyButtons. Columns with a json schema will additionally have an automatic formatter that indents and displays the popover content within an EuiCodeBlock.

If you want complete control over the rendering of the entire cell popover, use the renderCellPopover prop to pass a component. This allows you to do things like set your own wrappers and replace the default cell actions rendering with your own.

To make falling back to atoms of the default cell popover easier, several props are passed to your custom renderCellPopover function:

children - the direct JSX output of the cell's returned renderCellValue. It can be used (e.g.) if you want a custom wrapper or cell actions, but default popover content.
cellContentsElement - a direct reference to the cell's HTML content node, which allows accessing the cell's innerText for cases where raw non-JSX text is useful (e.g. copying).
cellActions - the direct JSX output of the default popover footer and buttons. Use this prop if you want custom popover content but default cell actions.
- If deliberately leaving out the default cellActions, you must re-implement your cell actions in the popover in some form. Leaving out cell actions available in the cell but not in the popover introduces UX inconsistencies and will confuse the end user.
DefaultCellPopover - the default popover component. Use this component if you only want custom popover content for certain schemas or columns and default popover rendering for other cells.
setCellPopoverProps - this callback is passed to allow customizing the cell expansion popover. Accepts any prop that EuiPopover accepts, except for button & closePopover, which is controlled by the data grid.

Take a look at the below example's demo code to see the above props in action.

Disabling cell expansion popovers

Popovers can sometimes be unnecessary for short form content, and can be disabled by setting columns.isExpandable to false. In the example below, we've turned off expansion on the suffix column.

To set isExpandable at a per-cell level instead of per-column, you can use the setCellProps callback passed by renderCellValue. The below example conditionally disables the expansion popover for boolean cells that are 'false'.

Cells with actions are always expandable

If columns.cellActions is defined, isExpandable will always be forced to true. This ensures that keyboard and screen reader users have access to all cell actions.

Focus

EuiDataGrid tracks and manages complicated focus state management based upon the content of the individual inner cells. The following scenarios are supported and tested:

Initial focus

When tabbing to the grid before it has received focus, the header cell is focused.
When tabbing away from the grid and then returning, the last focused cell will regain focus.
If the last focused cell has been scrolled out of view, the first header cell receives focus instead.

Click and key events

Clicking on an interactive cell or its content should focus on the cell.
The up, down, left, and right arrow keys can be pressed to navigate between cells.
For expandable cells, either the Enter or F2 keys can be pressed interchangeably to toggle the cell popover. The Escape key will close the popover.
For non-expandable cells with interactive content, either the Enter or F2 keys can be pressed to enter a focus trap, allowing users to Tab between the cell's content. The Escape key will exit the cell trap.
For non-expandable cells with no interactive content, the cell alone will receive focus, with no inner content action.

Don't turn off cell expansion when the width of the column is unknown

In general, you should change isExpandable to false only when you know the exact width and number of items that a cell will include. Control columns that contain row actions are a good example of when to use them. In certain scenarios, allowing multiple interactive elements in cells when you cannot control the width can lead to hidden focus because the content is truncated.

Cell context

The cellContext prop is an easy way of passing your custom data or context from the top level of EuiDataGrid down to the cell content rendered by your renderCellValue function component.

The primary use of the cell context API is performance: if your data relies on state from your app, it allows you to more easily define your renderCellValue function statically, instead of within your app, which in turn reduces the number of rerenders within your data grid.