Basic tables
EuiBasicTable is a high-level component that provides a consistent way to display and manage table data. At its simplest, it requires only two properties:
items
- an array of objects to display in the table, with one item per row. Thecolumns
property determines what data gets shown in each cell. You can userowProps
andcellProps
to customize the appearance of rows and cells by passing objects or functions that return objects.columns
- defines the table columns and how to extract data from each item to display in the cells.
This example shows the basic EuiBasicTable setup with the required items
and columns
properties and some display options for each column:
In the above example, some columns display the value as-is (like firstName
and lastName
). Other columns customize how the data appears before displaying it. You can customize the display in two ways (and you can use both):
- Data type hints - Tell the table what type of data you're showing (like the "Date of Birth" column using
date
type). This automatically adjusts built-in display components (for example, numbers become right-aligned, like in Excel). - Custom render function - Provide a
render
function that takes the value (and the item as a second argument) and returns the React component to display in the cell. This can be simple formatting (like the "Date of Birth" column) or complex React components (like the "Online" and "Github" columns).- Note: The basic table treats cells with a
render
function astextOnly: false
by default, which may cause unwanted line breaks. SettextOnly: true
to ensure proper text wrapping.
If a column name needs a longer description, you can add an icon with a tooltip using the columns.nameTooltip
property. This keeps the icon visible even if the text gets cut off, which is better than manually adding a React node to columns.name
.
If the column header is sortable, the tooltip applies to the entire cell instead of just the icon for better accessibility.
Row selection
The following example shows how to set up row selection using the selection
property. For automatic selection handling, where users control what gets selected, you can set initially selected items using selection.initialSelected
. Use selection.onSelectionChange
to track or respond to user selections.
For complete control over table selection, use selection.selected
instead (this requires selection.onSelectionChange
). This is useful when you want to handle selections based on user interactions with other parts of your UI.
Row actions
The following example shows "action" columns - special columns where you define actions for each row. The most basic actions are button
or icon
types, but you can also create custom actions.
Actions follow these UI/UX rules:
- Only 2 actions can be visible per row. When you define more than two actions, the first 2
isPrimary
actions stay visible, and all actions appear in a popover triggered by an ellipsis button. - Actions become semi-transparent when you hover over the row. With more than 2 actions, only the ellipsis button stays visible at all times.
- When one or more rows are selected, all individual actions are disabled. Users should use bulk actions outside the table instead.
Expanding rows
You can expand rows by providing an itemIdToExpandedRowMap
prop with the content you want to show inside the expanded row. When building your table manually (not using EuiBasicTable), you'll also need to add the isExpandedRow
prop to the row that will be revealed.
Table row classes
You can highlight specific rows or apply custom styling using the rowProps
prop.
It receives the current row data item as an argument, which you can use to add classes conditionally.
tsx code block:<EuiBasicTable rowProps={(user: User) => ({ className: user.online ? 'euiTableRow--marked' : '', })} />
There's a styling utility class available: euiTableRow--marked
This class highlights rows. Use the rowProps.className
prop to add the class to specific rows.
The utility class also includes hover styles.
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 columns have a footer
definition, the footer area will appear. By default, columns without a footer (undefined) will show an empty cell to keep the table layout consistent. Check out the custom tables page for more examples of working with table footers in EUI.
Table layout
EuiBasicTable uses 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 column widths while still using truncateText
, set the width of each column using the width
prop.
You can also set the vertical alignment (valign
) at the column level, which affects the cell contents for that entire column (excluding the header and footer).
Responsive tables
Tables are mobile-responsive by default, breaking down each row into its own card section and showing each table header above the cell contents. The default breakpoint where the table switches to cards is the m
window size, which you can customize with the responsiveBreakpoint
prop (like responsiveBreakpoint="s"
).
To never make your table responsive (for tables with very few columns), set responsiveBreakpoint={false}
. To always render your table in a mobile-friendly way, pass true
. The example below switches between true/false
for easy preview of mobile and desktop table layouts at all breakpoints.
To customize how your cells look in mobile vs. desktop view, use the mobileOptions
configuration. You can pass this object to each column item in EuiBasicTable or to EuiTableRowCell directly. See the "Snippet" tab in the example below, or the "Props" tab for all configuration options.
Manual pagination and sorting
EuiBasicTable's pagination
and sorting
properties only control the UI displayed on the table (like showing sorting arrows or pagination numbers). They don't actually handle paginating or sorting your items
data.
This is mainly useful for large amounts of API-based data, where storing or sorting all rows in memory would cause performance problems. Your API backend should handle sorting, filtering, and caching your data asynchronously.
For smaller datasets (hundreds of items or less) that don't use APIs, we recommend using EuiInMemoryTable, which automatically handles pagination, sorting, and searching in memory.
Pagination
The following example shows how to set up pagination using the pagination
property.
Sorting
The following example shows how to set up column sorting using the sorting
property and marking sortable columns with sortable: true
. To enable default sorting for every column, pass enableAllColumns: true
to the sorting
prop. If you don't want users to control the sort, you can pass readOnly: true
to the sorting
prop or to individual columns.
Unique identifiers required for sorting
When using sorting with EuiBasicTable, make sure each row has a unique identifier by passing unique id
values. Duplicate identifiers can cause sorting to display incorrect results, such as showing fewer items than expected.
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). ((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 |