Index table purpose and function
An index table displays a collection of objects of the same type, like orders or products. The main job of an index table is to help merchants get an at-a-glance view of the objects to perform actions or navigate to a full-page representation of it. Index tables function as a content format presenting individual resources with multiple columns of information, a system for taking action on one or more resources, and a way to navigate to an individual resource's details page.
Index table components
An index table is built from the following components and subcomponents: IndexTable, IndexTable.Row, IndexTable.Cell, Filters (optional), IndexFilters (optional), and Pagination (optional).
Index table does not provide operation logic
The index table component provides the UI elements for list selection, sorting, filtering, and pagination, but does not provide the logic for these operations. When a sort option is changed, filter added, or second page requested, you must handle that event (including any network requests) and then update the component with new props.
IndexTable.Row properties
IndexTable.Row has the following properties: children (ReactNode, table header or data cells), id (string, required, unique identifier for the row), selected (boolean | 'indeterminate', optional, indicates whether the row or related rows are selected), position (number, required, zero-indexed position used for Shift key multi-selection and selection range), tone (optional, 'subdued' | 'success' | 'warning' | 'critical', visually indicates row status with background color), disabled (optional, boolean, disables the row), selectionRange (optional, [number, number] tuple with first and last index of range, selects all non-disabled rows in range when selected), rowType (optional, 'data' | 'subheader' | 'child', defaults to 'data', 'subheader' looks and behaves as table header, 'child' rows are indented), accessibilityLabel (optional, string, label on row checkbox, defaults to 'Select {resourceName}'), onClick (optional, callback fired when row clicked, overrides default click behaviour), onNavigation (optional, callback (id: string) => void fired when row clicked and contains anchor with data-primary-link property set).
IndexTable.Cell properties
IndexTable.Cell has the following properties: as (optional, 'th' | 'td', element to render, defaults to 'td'), id (optional, string, unique ID on cell element), children (optional, ReactNode, cell contents), className (optional, string, adds class for custom cell width), flush (optional, boolean, removes cell padding, defaults to false), colSpan (optional, HTMLTableCellElement['colSpan'], for subheader cells only, number of columns cell should extend to), scope (optional, HTMLTableCellElement['scope'], for subheader cells, indicates cells the th element relates to), headers (optional, HTMLTableCellElement['headers'], space-separated list of th cell IDs that describe or apply to the cell, use for cells within rows that relate to subheader cell in addition to column header).
Index table best practices
Index tables should: have items that perform an action when clicked to navigate to resource's details page or provide more detail; customize content and layout of item rows to support merchant needs; support sorting if list can be long, especially if different merchant tasks benefit from different sort orders; support filtering if list can be long; paginate when list contains more than 50 items; use skeleton page component on initial page load if loading prop is true and items are processing; right-align numeric cells and titles with Text component; use numeric style with Text component for numeric cells. Index tables can optionally provide bulk actions for tasks often applied to many list items at once, and can hide bulk actions on small screens using the condensed prop (recommended for screens smaller than 490px using breakpoints-sm value), though hiding bulk actions means merchants cannot select multiple items at once and should only be used when bulk actions are not essential to workflow.
Index table content guidelines
Index tables should identify the type of resource usually with a heading (e.g., 'Products' or 'Showing 50 products'). They should indicate when not all members of a resource are being shown, using phrasing like 'Popular products this week' rather than just 'Products'. Bulk actions should follow the verb + noun formula. Filter options and applied filters should follow the content guidelines for filters.
Index table accessibility structure for subheaders
For IndexTable.Row subheaders, set the following props on IndexTable.Cell to ensure accessibility: set the zero-indexed table position of the first and last IndexTable.Row described by the subheader as a tuple array on the subheader row's selectionRange prop; provide a unique id on the IndexTable.Cell containing subheader content; set the element tag to 'th' on the as prop of the subheader IndexTable.Cell; set the subheader IndexTable.Cell scope prop to 'colgroup'. To associate the subheader IndexTable.Row with each IndexTable.Cell it describes, set the unique id from the subheader IndexTable.Cell on the headers prop of each related IndexTable.Cell (within rows whose position is within the selectionRange) along with the unique id of the corresponding column heading provided to IndexTable headings prop.
Index table keyboard support
IndexTable supports multi-selection of a range of rows by pressing and holding the Shift key while clicking or pressing Space on a row checkbox, then doing the same on another row's checkbox. All selectable rows between the selected checkboxes will also be selected. Merchants can select a group of rows at once by clicking or pressing Space on a subheader row's checkbox.
IndexTable.Row status prop replaced with tone
The IndexTable.Row component's status prop is replaced with tone. For example, <IndexTable.Row status="success" /> becomes <IndexTable.Row tone="success" />.
IndexTable.Row subdued prop replaced with tone
The IndexTable.Row component's subdued boolean prop is replaced with tone="subdued". For example, <IndexTable.Row subdued /> becomes <IndexTable.Row tone="subdued" />.