Data grid
EuiDataGrid is for displaying large amounts of tabular data. It is a better choice over
EUI tables when there are many columns, the data in those columns is fairly uniform, and when schemas and sorting are important for comparison. Although it is similar to traditional spreedsheet software, EuiDataGrid's current strengths are in rendering rather than creating content.Core concepts
- The grid allows you to optionally define an in memory level to have the grid automatically handle updating your columns. Depending upon the level chosen, you may need to manage the content order separately from the grid.
- Schemas allow you to tailor the render and sort methods for each column. The component ships with a few automatic schema detection and types, but you can also pass in custom ones.
- Unlike tables, the data grid forces truncation. To display more content your can customize popovers to display more content and actions into popovers.
- Grid styling can be controlled by the engineer, but augmented by user preference depending upon the features you enable.
- Control columns allow you to add repeatable actions and controls like checkboxes or buttons to your grid.
- The toolbar offers the user ways to manipulate the display and order of the data.
Top level props
Please check the props section below for more explanation on the lower level object types. The majority of the types are defined in the /datagrid/data_grid_types.ts file.
Data grid adapts to its container
When wrapped inside a container, like a dashboard panel, the grid will start hiding controls and adopt a more strict flex layout. Use the
minSizeForControls prop to control the min width to enables/disables grid controls based on available width.When placed within an EuiFlexGroup and EuiFlexItem, the data grid will have trouble shrinking to fit. To fix this, you will need to manually add a style of min-width: 0 to the EuiFlexItem.
Virtualization
Creating a lot of DOM nodes is computationally expensive, and EuiDataGrid uses a couple wrapping divs to build each cell. To help offset the cost of larger tables, cell virtualization can be opted into by constraining the grid's height and/or width. There are two ways to enable this functionality. First, height and/or width can be passed as props, which are applied to the grid's container style. Alternatively, if EuiDataGrid is unable to render at the full dimensions it needs due to screen real estate or other DOM constraints, it will overflow within a scrollable container and only render the visible cells.
Never toggle the height between a value and undefined.
Similar to React's rule of not switching between a controlled and uncontrolled input, EuiDataGrid does not accommodate for its height switching to or from undefined. For demonstration purposes, the example below uses a key to force EuiDataGrid to completely remount when its height changes between constrained & constrained heights.
Constrained by DOM
Props
EuiDataGrid
Prop | Description and type | Default value |
|---|---|---|
Prop columns# | Description and type An array of #EuiDataGridColumn objects. Lists the columns available and the schema and settings tied to it. EuiDataGridColumn[] | Default value Required |
Prop columnVisibility# | Description and type An array of #EuiDataGridColumnVisibility objects. EuiDataGridColumnVisibility | Default value Required |
Prop rowCount# | Description and type The total number of rows in the dataset (used by e.g. pagination to know how many pages to list). number | Default value Required |
Prop renderCellValue# | Description and type A function called to render a cell's value. Behind the scenes it is treated as a React component RenderCellValue | Default value Required |
Prop className# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop width# | Description and type Sets the grid's width, forcing it to overflow in a scrollable container with cell virtualization. Width<string | number> | Default value |
Prop height# | Description and type Sets the grid's height, forcing it to overflow in a scrollable container with cell virtualization. Height<string | number> | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop leadingControlColumns# | Description and type An array of #EuiDataGridControlColumn objects. Used to define ancillary columns on the left side of the data grid. EuiDataGridControlColumn[] | Default value |
Prop trailingControlColumns# | Description and type An array of #EuiDataGridControlColumn objects. Used to define ancillary columns on the right side of the data grid. EuiDataGridControlColumn[] | Default value |
Prop schemaDetectors# | Description and type An array of custom #EuiDataGridSchemaDetector objects. You can inject custom schemas to the grid to define the classnames applied. EuiDataGridSchemaDetector[] | Default value |
Prop cellContext# | Description and type An optional object of props passed to the CellContext | Default value |
Prop renderCellPopover# | Description and type An optional function that can be used to completely customize the rendering of cell popovers. If not specified, defaults to an Behind the scenes it is treated as a React component allowing hooks, context, and other React concepts to be used. JSXElementConstructor<EuiDataGridCellPopoverElementProps> | ((props: EuiDataGridCellPopoverElementProps) => ReactNode) | Default value |
Prop renderFooterCellValue# | Description and type An optional function called to render a footer cell. If not specified, no footer row is rendered. Behind the scenes it is treated as a React component RenderCellValue | Default value |
Prop renderCustomGridBody# | Description and type An optional function called to completely customize and control the rendering of This component is only meant as an escape hatch for extremely custom use cases. Behind the scenes, this function is treated as a React component, (args: EuiDataGridCustomBodyProps) => ReactNode | Default value |
Prop renderCustomToolbar# | Description and type An optional function called to customize placement of controls in EuiDataGrid's toolbar. Behind the scenes, this function is treated as a React component, (props: EuiDataGridCustomToolbarProps) => ReactElement | Default value |
Prop gridStyle# | Description and type Defines the initial style of the grid. Accepts a partial #EuiDataGridStyle object. EuiDataGridStyle | Default value |
Prop toolbarVisibility# | Description and type Allows you to configure what features the toolbar shows. Accepts either a boolean or #EuiDataGridToolBarVisibilityOptions object. boolean | EuiDataGridToolBarVisibilityOptions | Default value |
Prop inMemory# | Description and type A #EuiDataGridInMemory object to define the level of high order schema-detection and sorting logic to use on your data. EuiDataGridInMemory | Default value |
Prop pagination# | Description and type A #EuiDataGridPaginationProps object. Omit to disable pagination completely. EuiDataGridPaginationProps | Default value |
Prop sorting# | Description and type A #EuiDataGridSorting object that provides the sorted columns along with their direction. Provides a callback for when it changes. EuiDataGridSorting | Default value |
Prop onColumnResize# | Description and type A callback for when a column's size changes. Callback receives EuiDataGridOnColumnResizeHandler | Default value |
Prop minSizeForControls# | Description and type Defines a minimum width for the grid to show all controls in its toolbar. number | Default value |
Prop virtualizationOptions# | Description and type Allows customizing the underlying react-window grid props. Partial<Omit<VariableSizeGridProps<any>, "children" | "width" | "height" | "ref" | "rowHeight" | "rowCount" | "columnCount" | "columnWidth" | "itemData" | "innerRef" | "outerRef" | "innerElementType" | "useIsScrolling">> | Default value |
Prop rowHeightsOptions# | Description and type A #EuiDataGridRowHeightsOptions object that provides row heights options. EuiDataGridRowHeightsOptions | Default value |
Prop ref# | Description and type Type: Ref<EuiDataGridRefProps> | Default value |