Table

Features still in consideration include:

• Responsive variants (cards with repeated labels, transpose table)
• Column pinning to support horizontal scrolling
• Header-less table
• Filtering
• Column width options (fixed, grow, auto, ellipsis, tooltip)
• Header-less columns (content between columns, e.g. formula operators)
• Sticky headers

Best Practices

Tables should:

• Be used to show homogeneous content.
• Help users visualize values from a data set.
• Only display values supporting the data's purpose.
• Include a heading to help identify the contents of the table at-a-glance.
• Provide links to view additional or related content within the first column of a table.

Alignment

Column content types can be varied using component props to enable the following alignment rules:

• Numerical values should be right aligned
• Textual values should be left aligned
• Headers (where present) should align with their data

Content guidelines

Tables should:

• Include concise but descriptive headers
• Avoid truncating content where possible

Tables can also:

• Support items that perform an action when clicked. For example, navigating to the item's details page or provide more detail about the item.
• Provide bulk actions for tasks that are applicable to many items at once.

Examples

Simple table

Used whenever the tabular data is directly related to the preceding or subsequent content. Simple tables should be used as a direct child of a Card component.

Full Width Table

Add the prop fullWidth to allow a table to fill the parent element's width.

Tables that fill a Card

Used whenever the tabular data alone represents a cohesive set of content. Should be used with a title prop and may include optional titleIcon and actions.

Tables that fill a Card without a Heading

Used whenever the tabular data alone represents a cohesive set of content, without a table card heading using showCardWithoutHeading flag.

Maintain accessibility by providing an ariaLabel, and optionally also a heading or label above the card.

May include optional actions.

Tables with a Transparent Background

Use the transparent flag to inherit the parent element's background color.

Table with actions

Tables that fill a card can also offer actions that operate on the table data, or are related to the table content.

Consider wrapping actions in an EzLayout to manage how actions stack at smaller breakpoints.

Table with search

To filter data with a search filter, provide an EzSearchInput as an action, with corresponding search term state and a function to handle filtering the data when the search term changes.

If the search filter needs to be disabled in the case of very large datasets, the recommendation is to first work with a designer to show usable tables with more user-friendly pre-filtered datasets. If that is not possible and performance becomes an issue, conditioanlly hide the search input or disable it.

Custom cell rendering

Use when more fine-grained control over the table content is desired (in favor of simple Textual/Numerical content). To provide custom content, the component property of each column can be provided any React element or custom React component. Custom components will be provided an item prop with the record to be rendered.

To use a custom cell to render links to additional content, see the Row highlighting and selection example;

Clickable rows

Use when offering links to see more information or related content to ensure the click surface of the link spans the entire table row.

When using custom cell rendering the component property of a column is also provided a linkRef which allows the table to target specific links to trigger when the table row is clicked.

Note: Typically, only the first column should provide links to view additional or related content. The linkRef prop should only be applied to a single column's component, as clicking the row should trigger navigation on a single link.

Bulk row selection

Use when multiple rows of a table can be selected together in order to perform an action in bulk.

When enabled, table selection provides the user with options to select or deselect either individual rows from a data set, or all the currently visible rows in the table. When using pagination, table selection enables all rows to be selected from the current page, or from the data set as a whole. To see selection and pagination features used together, see the bulk row selection across pages example.

The following properties are required when using selection:

• selection
  • onRowSelectClick (required): an event that is fired when the user toggles to select or deselect a row in the table. The event handler function will receive two arguments, the click event and an object containing the row's data item.
  • onBulkSelectClick (required): an event that is fired when the user toggles to select or deselect all currently visible rows.
  • isRowSelected (required): a function used to determine whether a row is currently marked as selected or not. The function accepts the row's item object as an argument, and should return true if the item is selected, or false otherwise.

With sortable columns

Use column sorting to help users find items quicker in larger data sets. Column sorting is switched off for all columns by default. Table data can only be sorted by a single column at a time.

To turn on column sorting, set the sortable flag for each column where sorting is supported.

When a column header is pressed, the onSortClick callback will be called and provided with column metadata and the direction in which to sort the data, either asc or desc for ascending or descending respectively. When sorting a column for the first time, the initial sort direction will be ascending.

When providing pre-sorted data to EzTable, the relevant column should have a defaultSort value set to either asc or desc to indicate the sort order applied to the data.

The following example performs client-side sorting, using the key metadata of a column to indicate which column to sort by.

Columns with Icons

To add an icon to a column header, add icon to the column. Recipe supports EzIcon, which can be wrapped in EzTooltip.

Consider and choose the appropriate size, color, and accessibility of each icon added to table column headers in the context of the rest of the columns.

Pagination

Pagination can be used to display a large data set, either local or remote, with a set number of rows per page.

Pagination is enabled by adding the pagination attribute to EzTable with the following properties:

• currentPage (required): an integer that represents the default starting page for the data set. This number is 1-indexed.
• totalRows (required): an integer that represents the total number of items in the data set.
• rowsPerPage (required): an integer used to determine how many items to show per page in the table.
• rowsPerPageOptions (required): an array of integers that is displayed at the bottom right of the table used to change rowsPerPage.
• onPrevPageClick (required): an event that is fired when the "Previous Page" link is clicked.
• onNextPageClick (required): an event that is fired when the "Next Page" link is clicked.
• onRowsPerPageChange (required): an event that is fired when the "n rows per page" select value is changed.
• totalFilteredRows (optional): number of rows after data has been filtered, if using a filter

To see selection and pagination features used together, see the bulk row selection across pages example.

Using bulk selection across pages may interact with your custom actions in an unexpected way (for example, with a search filter). Be sure to test all logic to ensure everything works as expected.

Local Data

Local Data with Sorting

Bulk row selection across pages

When interacting with large data sets that span multiple pages, managing the selection of records in order to perform an action in bulk can be a challenge. To simplify this experience, users are presented with a summary of their selection with options to select all records across all pages of the data set, or clear their current selection.

To enable this feature, the following additional properties are available when using selection and pagination features together:

• selection
  • onSelectAllClick (required): an event that is fired when the "Select all" message is clicked.
  • onSelectNoneClick (required): an event that is fired when the "Clear selection" message is clicked.
  • totalRowsSelected (required): number of total rows selected across pages from your selection state
  • disableMultiPageSelection: true (optional): set to true if you don't want to allow the user to select all rows on all pages.

When offering pagination and selection, users should be offered options:

• Selecting individual records
• Selecting all records for the entire page
• Selecting all records for the entire data-set

Advanced filtering

This is an advanced example of how to use multiple filters in a table.

To avoid performance degradation

• Do NOT use client-side filtering for large datasets (hundreds or more entries), it can make the table unusable. Prefer server-side filtering, in most cases.
• Prefer making server-side API calls to filter the actual dataset as the client-side filters change, with appropriate debouncing based on the situation.