Basic tables
EuiBasicTable is an opinionated high level component that standardizes both display and injection. At its most simple it only accepts two properties:
itemsare 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 thecolumnsproperty. You can definerowPropsandcellPropsprops 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.columnsdefines 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, with certain display configurations per-column:
In the above example, some columns displayed the value as-is (e.g. firstName and lastName fields). Other columns customized the display of the data before it was 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, like in Excel). - Provide a
renderfunction 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" and "Github" columns).- Note: the basic table will treat any cells that use a
renderfunction as beingtextOnly: false. This may cause unnecessary word breaks. ApplytextOnly: trueto ensure it breaks properly.
If a column name needs a longer description, an icon with a tooltip can be used. This can be done using the columns.nameTooltip property. This approach ensures that the icon remains visible even if the text gets truncated, unlike manually using a React node for columns.name.
Row selection
The following example shows how to configure row 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.
Row actions
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
isPrimaryactions 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.
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 a footer to a table
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
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.
Manual pagination and sorting
EuiBasicTable's pagination and sorting properties only affect the UI displayed on the table (e.g. rendering sorting arrows or pagination numbers). They do not actually handle showing paginated or sorting your items data.
This is primarily useful for large amounts of API-based data, where storing or sorting all rows in-memory would pose significant performance issues. Your API backend should then asynchronously handle sorting/filtering/caching your data.
For non-asynchronous and smaller datasets use-cases (in the hundreds or less), we recommend using EuiInMemoryTable, which automatically handles pagination, sorting, and searching in-memory.
Pagination
The following example shows how to configure pagination via the pagination property.
Sorting
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.
Props
EuiBasicTable
Prop | Description and type | Default value |
|---|---|---|
Prop items# | Description and type A list of objects to appear in the table - an item per row T[] | Default value Required |
Prop columns# | Description and type An array of one of the objects: #EuiTableFieldDataColumnType, #EuiTableComputedColumnType or #EuiTableActionsColumnType. 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. 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 ItemId<T> | Default value |
Prop itemIdToExpandedRowMap# | Description and type Row expansion uses the itemId prop to identify each row ItemIdToExpandedRowMap | Default value |
Prop cellProps# | Description and type Applied to object | CellPropsCallback<T> | Default value |
Prop error# | Description and type Error message to display 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." 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 string | Default value |
Prop loading# | Description and type Provides an infinite loading indicator boolean | Default value |
Prop noItemsMessage# | Description and type Message to display if table is empty 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 ((criteria: Criteria<T>) => void) | ((criteria: CriteriaWithPagination<T>) => void) | Default value |
Prop pagination# | Description and type Configures #Pagination Pagination | Default value |
Prop rowProps# | Description and type Applied to object | RowPropsCallback<T> | Default value |
Prop selection# | Description and type Configures #EuiTableSelectionType EuiTableSelectionType<T> | Default value |
Prop sorting# | Description and type Configures #EuiTableSortingType EuiTableSortingType<T> | Default value |
Prop tableLayout# | Description and type Sets the table-layout CSS property. Note that auto tableLayout prevents truncateText from working properly. "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 Pass string | boolean | Default value m |