Tables

EUI provides opinionated and non-opinionated ways to build tables

Tables can get complicated very fast. If you're just looking for a basic table with pagination, sorting, checkbox selection, and actions then you should use EuiBasicTable. It's a high level component that removes the need to worry about constructing individual components together. You simply arrange your data in the format it asks for.

However if your table is more complicated, you can still use the individual table components like rows, headers, and pagination separately to do what you need. Find examples for that at the bottom of this page.

A basic table

EuiBasicTable is an opinionated high level component that standardizes both display and injection. At its most simple it only accepts two properties:

items are an array of objects that should be displayed in the table; one item per row. The exact item data that will be rendered in each cell in these rows is determined by the columns property. You can define rowProps and cellProps props which can either be objects or functions that return objects. The returned objects will be applied as props to the rendered rows and row cells, respectively.
columns defines what columns the table has and how to extract item data to display each cell in each row.

This example shows the most basic form of the EuiBasicTable. It is configured with the required items and columns properties. It shows how each column defines the data it needs to display per item. Some columns display the value as is (e.g. firstName and lastName fields for the user column). Other columns customize the display of the data before it is injected. This customization can be done in two (non-mutual exclusive) ways:

Provide a hint about the type of data (e.g. the "Date of Birth" column indicates that the data it shows is of type date). Providing data type hints will cause built-in display components to be adjusted (e.g. numbers will become right aligned, just like Excel).
Provide a render function that given the value (and the item as a second argument) returns the React node that should be displayed as the content of the cell. This can be as simple as formatting values (e.g. the "Date of Birth" column) to utilizing more complex React components (e.g. the "Online", "Github", and "Nationality" columns as seen below). Note: the basic table will treat any cells that use a render function as being textOnly: false. This may cause unnecessary word breaks. Apply textOnly: true to ensure it breaks properly.

Adding pagination to a table

The following example shows how to configure pagination via the paginationproperty.

Adding sorting to a table

The following example shows how to configure column sorting via the sorting property and flagging the sortable columns as sortable: true. To enable the default sorting ability for every column, pass enableAllColumns: true to the sorting prop. If you don't want the user to have control over the sort you can pass readOnly: true to the sorting prop or per column.

Adding selection to a table

The following example shows how to configure selection via the selection property. For uncontrolled usage, where selection changes are determined entirely by the user, you can set items to be selected initially by passing an array of items to selection.initialSelected. You can also use selected.onSelectionChange to track or respond to the items that users select.

To completely control table selection, use selection.selected instead (which requires passing selected.onSelectionChange). This can be useful if you want to handle table selections based on user interaction with another part of the UI.

Controlled selection

The following example shows how to add a footer to your table by adding footer to your column definitions. If one or more of your columns contains a footer definition, the footer area will be visible. By default, columns with no footer specified (undefined) will render an empty cell to preserve the table layout. Check out the Build a custom table section below for more examples of how you can work with table footers in EUI.

Expanding rows

You can expand rows by passing in a itemIdToExpandedRowMap prop which will contain the content you want rendered inside the expanded row. When building out your table manually (not using EuiBasicTable), you will also need to add the prop isExpandedRow to the row that will be revealed.

Adding actions to table

The following example demonstrates "actions" columns. These are special columns where you define per-row, item level actions. The most basic action you might define is a type button or icon though you can always make your own custom actions as well.

Actions enforce some strict UI/UX guidelines:

There can only be up to 2 actions visible per row. When more than two actions are defined, the first 2 isPrimary actions will stay visible, an ellipses icon button will hold all actions in a single popover.
Actions change opacity when user hovers over the row with the mouse. When more than 2 actions are supplied, only the ellipses icon button stays visible at all times.
When one or more table row(s) are selected, all item actions are disabled. Users should be expected to use some bulk action outside the individual table rows instead.

Table layout

EuiBasicTable has a fixed layout by default. You can change it to auto using the tableLayout prop. Note that setting tableLayout to auto prevents the truncateText prop from working properly. If you want to set different columns widths while still being able to use truncateText, set the width of each column using the width prop.

You can also set the vertical alignment (valign) at the column level which will affect the cell contents for that entire column excluding the header and footer.

Responsive tables

Tables will be mobile-responsive by default, breaking down each row into its own card section and individually displaying each table header above the cell contents. The default breakpoint at which the table will responsively shift into cards is the m window size, which can be customized with the responsiveBreakpoint prop (e.g., responsiveBreakpoint="s").

To never render your table responsively (e.g. for tables with very few columns), you may set responsiveBreakpoint={false}. Inversely, if you always want your table to render in a mobile-friendly manner, pass true. The below example table switches between true/false for quick/easy preview between mobile and desktop table UIs at all breakpoints.

To customize your cell's appearance/rendering in mobile vs. desktop view, use the mobileOptions configuration. This object can be passed to each column item in EuiBasicTable or to EuiTableRowCell directly. See the "Snippet" tab in the below example, or the "Props" tab for a full list of configuration options.

Build a custom table from individual components

As an alternative to EuiBasicTable you can instead construct a table from individual low level, basic components like EuiTableHeader and EuiTableRowCell. Below is one of many ways you might set this up on your own. Important to note are how you need to set individual props like the truncateText prop to cells to enforce a single-line behavior and truncate their contents, or set the textOnly prop to false if you need the contents to be a direct descendent of the cell.

Responsive extras

You must supply a mobileOptions.header prop equivalent to the column header on each EuiTableRowCell so that the mobile version will use that to populate the per cell headers.

Also, custom table implementations will not auto-populate any header level functions like selection and filtering. In order to add mobile support for these functions, you will need to implement the EuiTableHeaderMobile component as a wrapper around these and use EuiTableSortMobile and EuiTableSortMobileItem components to supply mobile sorting. See demo below.

Prop	Description and type	Default value
Prop items#	Description and type A list of objects to appear in the table - an item per row Type: `T[]`	Default value Required
Prop columns#	Description and type An array of one of the objects: #EuiTableFieldDataColumnType, #EuiTableComputedColumnType or #EuiTableActionsColumnType. Type: `EuiBasicTableColumn<T>[]`	Default value Required
Prop className#	Description and type Type: `string`	Default value
Prop aria-label#	Description and type Defines a string value that labels the current element. @see aria-labelledby. Type: `string`	Default value
Prop data-test-subj#	Description and type Type: `string`	Default value
Prop css#	Description and type Type: `Interpolation<Theme>`	Default value
Prop itemId#	Description and type Describes how to extract a unique ID from each item, used for selections & expanded rows Type: `ItemId<T>`	Default value
Prop itemIdToExpandedRowMap#	Description and type Row expansion uses the itemId prop to identify each row Type: `ItemIdToExpandedRowMap`	Default value
Prop cellProps#	Description and type Applied to `EuiTableRowCell` Type: `object \| CellPropsCallback<T>`	Default value
Prop error#	Description and type Error message to display Type: `string`	Default value
Prop tableCaption#	Description and type Describes the content of the table. If not specified, the caption will be "This table contains {itemCount} rows." Type: `string`	Default value
Prop rowHeader#	Description and type Indicates which column should be used as the identifying cell in each row. Should match a "field" prop in FieldDataColumn Type: `string`	Default value
Prop loading#	Description and type Provides an infinite loading indicator Type: `boolean`	Default value
Prop noItemsMessage#	Description and type Message to display if table is empty Type: `ReactNode`	Default value `( <EuiI18n token="euiBasicTable.noItemsMessage" default="No items found" /> )`
Prop onChange#	Description and type Called whenever pagination or sorting changes (this property is required when either pagination or sorting is configured). See #Criteria or #CriteriaWithPagination Type: `((criteria: Criteria<T>) => void) \| ((criteria: CriteriaWithPagination<T>) => void)`	Default value
Prop pagination#	Description and type Configures #Pagination Type: `Pagination`	Default value
Prop rowProps#	Description and type Applied to `EuiTableRow` Type: `object \| RowPropsCallback<T>`	Default value
Prop selection#	Description and type Configures #EuiTableSelectionType Type: `EuiTableSelectionType<T>`	Default value
Prop sorting#	Description and type Configures #EuiTableSortingType Type: `EuiTableSortingType<T>`	Default value
Prop tableLayout#	Description and type Sets the table-layout CSS property. Note that auto tableLayout prevents truncateText from working properly. Type: `"auto" \| "fixed"`	Default value `fixed`
Prop compressed#	Description and type Type: `boolean`	Default value
Prop responsiveBreakpoint#	Description and type Named breakpoint. Below this size, the table will collapse into responsive cards. Pass `false` to never collapse to a mobile view, or inversely, `true` to always render mobile-friendly cards. Type: `string \| boolean`	Default value `m`

Prop	Description and type	Default value
Prop showPerPageOptions#	Description and type Option to completely hide the "Rows per page" selector. Type: `boolean`	Default value `true`
Prop itemsPerPage#	Description and type Current selection for "Rows per page". Pass `0` to display the selected "Show all" option and hide the pagination. Type: `number`	Default value `10`
Prop itemsPerPageOptions#	Description and type Custom array of options for "Rows per page". Pass `0` as one of the options to create a "Show all" option. Type: `number[]`	Default value `[10, 25, 50]`
Prop onChangeItemsPerPage#	Description and type Click handler that passes back selected `pageSize` number Type: `ItemsPerPageChangeHandler`	Default value
Prop onChangePage#	Description and type Type: `(pageIndex: number) => void`	Default value
Prop aria-controls#	Description and type Requires the `id` of the table being controlled Type: `string`	Default value
Prop aria-label#	Description and type Type: `string`	Default value
Prop responsive#	Description and type Automatically reduces to the `compressed` version on smaller screens. Remove completely with `false` or provide your own list of responsive breakpoints. Type: `false \| string[]`	Default value
Prop compressed#	Description and type If true, will only show next/prev arrows and simplified number set. Type: `boolean`	Default value
Prop pageCount#	Description and type The total number of pages. Pass `0` if total count is unknown. Type: `number`	Default value
Prop activePage#	Description and type The current page using a zero based index. So if you set the activePage to 1, it will activate the second page. Pass `-1` for forcing to last page. Type: `number`	Default value

Prop	Description and type	Default value
Prop anchorPosition#	Description and type Type: `"upCenter" \| "upLeft" \| "upRight" \| "downCenter" \| "downLeft" \| "downRight" \| "leftCenter" \| "leftUp" \| "leftDown" \| "rightCenter" \| "rightUp" \| "rightDown"`	Default value
Prop items#	Description and type Type: `ItemProps[]`	Default value
Prop className#	Description and type Type: `string`	Default value
Prop aria-label#	Description and type Type: `string`	Default value
Prop data-test-subj#	Description and type Type: `string`	Default value
Prop css#	Description and type Type: `Interpolation<Theme>`	Default value

Prop	Description and type	Default value
Prop onSort#	Description and type Callback to know when an item has been clicked Type: `() => void`	Default value
Prop isSorted#	Description and type Indicates current option is the sorted on column Type: `boolean`	Default value
Prop isSortAscending#	Description and type Indicates which direction the current column is sorted on Type: `boolean`	Default value
Prop ariaLabel#	Description and type Type: `string`	Default value
Prop className#	Description and type Type: `string`	Default value
Prop aria-label#	Description and type Type: `string`	Default value
Prop data-test-subj#	Description and type Type: `string`	Default value
Prop css#	Description and type Type: `Interpolation<Theme>`	Default value