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.

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.