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 choosen you may need to manage the content order separate 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.
Cell contains interactive content.
Snippet with every feature in use
Here is a complicated data grid example meant to give you an idea of the data structure and callbacks you'll need to provide if you were utilizing all the features.
<EuiDataGrid
// Optional. Will try to autodectect schemas and do sorting and pagination in memory.
inMemory={{ level: 'sorting' }}
// Required. There are 200 total records.
rowCount={200}
// Required. Sets up three columns, the last of which has a custom schema we later define down below.
// The second column B won't allow clicking in to see the content in a popup.
columns={[{ id: 'A' }, { id: 'B', isExpandable: false }, {id: 'C', schema: 'franchise'}]}
// Optional. This allows you to initially hide columns. Users can still turn them on.
columnVisibility={{
visibleColumns: ['A', 'C'],
setVisibleColumns: () => {},
}}
// Optional. Customize the content inside the cell. The current example outputs the row and column position.
// Often used in combination with useEffect() to dynamically change the render.
renderCellValue={({ rowIndex, columnId }) =>
`${rowIndex}, ${columnId}`
}
// Optional. Add pagination.
pagination={{
pageIndex: 1,
pageSize: 100,
pageSizeOptions: [50, 100, 200],
onChangePage: () => {},
onChangeItemsPerPage: () => {},
}}
// Optional, but required when inMemory is set. Provides the sort and gives a callback for when it changes in the grid.
sorting={{
columns: [{ id: 'C', direction: 'asc' }],
onSort: () => {},
}}
// Optional. Allows you to configure what features the toolbar shows.
// The prop also accepts a boolean if you want to toggle the entire toolbar on/off.
toolbarVisibility={{
showColumnSelector: false
showStyleSelector: false
showSortSelector: false
showFullScreenSelector: false
}}
// Optional. Change the initial style of the grid.
gridStyle={{
border: 'all',
fontSize: 'm',
cellPadding: 'm',
stripes: true,
rowHover: 'highlight',
header: 'shade',
}}
// Optional. Provide additional schemas to use in the grid.
// This schema 'franchise' essentially acts like a boolean, looking for Star Wars or Star Trek in a column.
schemaDetectors={[
{
type: 'franchise',
// Try to detect if column data is this schema. A value of 1 is the highest possible. A (mean_average - standard_deviation) of .5 will be good enough for the autodetector to assign.
detector(value) {
return value.toLowerCase() === 'star wars' ||
value.toLowerCase() === 'star trek'
? 1
: 0;
},
// How we should sort data matching this schema. Again, a value of 1 is the highest value.
comparator(a, b, direction) {
const aValue = a.toLowerCase() === 'star wars';
const bValue = b.toLowerCase() === 'star wars';
if (aValue < bValue) return direction === 'asc' ? 1 : -1;
if (aValue > bValue) return direction === 'asc' ? -1 : 1;
return 0;
},
// Text for what the ASC sort does.
sortTextAsc: 'Star Wars-Star Trek',
// Text for what the DESC sort does.
sortTextDesc: 'Star Trek-Star Wars',
// EuiIcon to signify this schema.
icon: 'star',
// The color to use for the icon.
color: '#000000',
},
]}
// Optional. Mapped against the schema, provide custom layout and/or content for the popover.
popoverContents={{
numeric: ({ children, cellContentsElement }) => {
// `children` is the datagrid's `renderCellValue` as a ReactElement and should be used when you are only wrapping the contents
// `cellContentsElement` is the cell's existing DOM element and can be used to extract the text value for processing, as below
// want to process the already-rendered cell value
const stringContents = cellContentsElement.textContent;
// extract the groups-of-three digits that are right-aligned
return stringContents.replace(/((\d{3})+)$/, match =>
// then replace each group of xyz digits with ,xyz
match.replace(/(\d{3})/g, ',$1')
);
},
}}
/>
General props explanation
Please check the props tab in the example above for more explanation on the lower level object types. The majority of the types are defined in the /data_grid/data_grid_types.ts file.
- columns
- An array of
EuiDataGridColumn
objects. Lists the columns available and the schema and settings tied to it. - inMemory
- A
EuiDataGridInMemory
object to define the level of high order schema-detection and sorting logic to use on your data. Try to set it when possible. If omitted, disables all enhancements and assumes content is flat strings. - columnVisibility
- An array of
EuiDataGridColumnVisibility
objects. Defines which columns are visible in the grid and the order they are displayed. - schemaDetectors
- An array of custom
EuiDataGridSchemaDetector
objects. You can inject custom schemas to the grid to define the classnames applied. - popoverContents
- An object mapping
EuiDataGridColumn
schemas to a custom popover render. This dictates the content of the popovers when you click into each cell. - rowCount
- The total number of rows in the dataset (used by e.g. pagination to know how many pages to list).
- gridStyle
- Defines the look of the grid. Accepts a partial
EuiDataGridStyle
object. Settings provided may be overwritten or merged with user defined preferences iftoolbarVisibility.showStyleSelector
is set to true (which is the default). - toolbarVisibility
- Accepts either a boolean or
EuiDataGridTooBarVisibilityOptions
object. When used as a boolean, defines the visibility of entire toolbar. When passed an object allows you to turn off individual controls within the toolbar. - renderCellValue
- A function called to render a cell's value. Behind the scenes it is treated as a React component allowing hooks, context, and other React concepts to be used. The function receives a
EuiDataGridCellValueElement
as its only argument. - pagination
- A
EuiDataGridPagination
object. Omit to disable pagination completely. - sorting
- A
EuiDataGridSorting
object that provides the sorted columns along with their direction. Omit to disable, but you'll likely want to also turn off the user sorting controls through thetoolbarVisibility
prop.