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 output 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.
Conditionally customizing cell popover content
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.
Completely customizing cell popover rendering
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 returnedrenderCellValue. 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'sinnerTextfor 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 thatEuiPopoveraccepts, except forbutton&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.
Props
EuiDataGridCellValueElementProps
Prop | Description and type | Default value |
|---|---|---|
Prop setCellProps# | Description and type Callback function to set custom props & attributes on the cell's wrapping (props: EuiDataGridSetCellProps) => void | Default value Required |
Prop isExpandable# | Description and type Whether or not the cell is expandable, comes from the #EuiDataGridColumn boolean | Default value Required |
Prop isExpanded# | Description and type Whether or not the cell is expanded boolean | Default value Required |
Prop isDetails# | Description and type When rendering the cell, boolean | Default value Required |
Prop rowIndex# | Description and type Index of the row being rendered, 0 represents the first row. This index always includes number | Default value Required |
Prop colIndex# | Description and type Index of the column being rendered, 0 represents the first column. This index accounts number | Default value Required |
Prop columnId# | Description and type ID of the column being rendered, the value comes from the #EuiDataGridColumn string | Default value Required |
Prop schema# | Description and type The schema type of the column being rendered string | Default value |
EuiDataGridCellPopoverElementProps
Prop | Description and type | Default value |
|---|---|---|
Prop children# | Description and type The default Allows wrapping the rendered content: ReactNode | Default value Required |
Prop cellContentsElement# | Description and type References the div element the cell contents have been rendered into. Primarily useful for processing the rendered text HTMLDivElement | Default value Required |
Prop cellActions# | Description and type An ReactNode | Default value Required |
Prop DefaultCellPopover# | Description and type For certain columns or schemas, you may want to fall back to the standard EuiDataGrid popover display. JSXElementConstructor<EuiDataGridCellPopoverElementProps> | Default value Required |
Prop setCellPopoverProps# | Description and type Allows passing props to the wrapping cell expansion popover and panel. (props: Omit<EuiPopoverProps, "button" | "closePopover">) => void | Default value Required |
Prop rowIndex# | Description and type Index of the row being rendered, 0 represents the first row. This index always includes number | Default value Required |
Prop colIndex# | Description and type Index of the column being rendered, 0 represents the first column. This index accounts number | Default value Required |
Prop columnId# | Description and type ID of the column being rendered, the value comes from the #EuiDataGridColumn string | Default value Required |
Prop schema# | Description and type The schema type of the column being rendered string | Default value |