Skip to main contenteBay Playbook

Table

v1.1

Tables are used to organize and display data efficiently to provide users with insights and potential actions.

  • CSS
  • Marko
  • React
Stylized artwork for a table component.

Considerations

Organized

Tables are organized logically with clear hierarchy.

Intuitive

Tables are easy to use and behave as expected.

Interactive

Tables allow interaction and customization for greater control.

Anatomy

Number 1 points to the table title which is labeled “Orders”. Number 2 points to the Filter Bar component. Number 3 points to the tables’ tool bar. Number for points to the main rows and columns of the tables’ data set. Number 5 points the pagination for the table.
  1. Title
  2. Filter bar
  3. Tool bar
  4. Table content
  5. Pagination

Properties

Column label

The column label names the data in the column. Keep labels short and specific so users can distinguish columns at a glance.

  • Use sentence case
  • No ending punctuation
  • Use a noun or noun phrase
  • Keep to 1–3 words
Two column labels shown. One reads “Order #”, the other reads “Price”.

Selection

Bulk actions are functions that may be performed on multiple items within a table. Once the user selects at least one row from the table, the batch action bar appears and replaces the filter bar with actions they can take. To close “bulk edit mode”, the user can cancel or deselect the items.

Table displaying a list of orders. The table includes selectable rows with checkboxes, product images, and other order details. Each row shows an item overview, SKU number, quantity, order number, and order placement date.

Density

Our tables are available in 3 different row sizes: Compact, Default, and Relaxed. All cells have a 16px left/right padding while the top/bottom have a minimum padding of 12px.

Image displaying three rows of a data table, each with different row heights. Row 1 is compact and has a height of 64. Row 2 is default and has a height of 80. Row 3 is cozy and has a height of 112.

Image

For rows containing images or other media types, three sizes are available: Small, Medium, and Large.

Diagram showing three rows of a data table, each with a different row height. The first row is labeled '40' with a small-sized image of a sneaker, the second row '56' with a medium-sized image, and the third row '72' with a large-sized image.

Order

Column reordering is available to give users more control over their workflows and data sets.

Table showing a dropdown labeled “edit table” opened showing menu options for customizing “Table density”, “Column order”, and “Column width”

Cell types

Simple

Simple cells are structured to accommodate a lead, middle, and trailing slot for content.

Example of a simple cell layout with a text string.

Numeric

Numeric cells display quantitative data like prices, counts, and percentages.

  • Use numerals, not words (e.g., 3, not three)
  • Use consistent decimal precision within a column
  • Include the appropriate unit or currency symbol
A structured data table with three columns titled 'Order #', 'Price', and 'Growth', displaying three rows of data. The order column includes an order number. The Price column shows the price in USD, and “growth” column figures with an up or down arrow indicating the percentage change.

Field

Field cells let users edit data inline and display in an enabled state to signal that the cell is editable.

The table cell showing an enabled text field.

Dropdown

Dropdown cells let users make quick selections inline. Each option should be short, distinct, and easy to scan.

  • Use sentence case, except for proper nouns or branded terms
  • No ending punctuation
  • Use parallel structure

Learn more about Dropdowns.

Interactive dropdown menu for a product listing showing condition options. The selected option is 'New with box' with other available conditions listed, including 'New without box', 'Pre-owned', and 'Used'. 

Actions

Action cells give users controls for a specific row. Labels should name the outcome and stay consistent across all rows.

  • Use sentence case
  • No ending punctuation
  • Use a [verb] [noun] or [verb] [article] [noun] pattern
  • Aim for 1-3 words

Button combos

  • CTA button
  • CTA button + overflow button
  • Icon button
  • Icon button + overflow button
  • Overflow button
Five button combos are shown for Actions. CTA button, CTA button + overflow button, Icon button, Icon button + overflow button, and overflow button.

Status

Status cells show the current state of a row. Labels should be short, specific, and recognizable without surrounding context

  • Use all caps for the visual treatment
  • Write in sentence case for screen readers
  • No articles, prepositions, or punctuation
Table column showing three distinct statuses: 'WAITING PAYMENT' in red, 'PAID' in blue, and 'READY TO SHIP' in green. Each status is enclosed in a colored box to visually represent the current state of an order, facilitating quick recognition and decision-making for the user.

Behavior

Loading

Loading should be unobtrusive and seamless—minimizing any jarring flashes or content shifts whenever possible. When tables are in a loading state, the content is replaced with a simplified skeleton loader that preserves context as the updated or new information loads.

Table loading updated content.

Sorting

A sorted data table has three states: Unsorted, Sorted-up, and Sorted-down. The icon indicates the current sorted state and is only shown if sorting is available.

Table showing unsorted table data set.

Unsorted (Sort)

Table showing sorted up table data set.

Sorted-up (Sort-up)

Table showing sorted down table data set.

Sorted-down (Sort-down)

Scrolling

The table header is sticky on vertical scroll. If the table extends beyond the screen then the table will scroll horizontally. Tables have a max height of 90% of the viewport.

A table with a fixed table header with the table’s content scrolling beneath it.

Column width

An adjusted column width indicator is presented in a focused editing mode that is visually similar to bulk editing, with explicit actions to save, reset, or cancel.

Minimum and Maximum

Columns have a minimum width of 124px and a maximum width of 400px, except for selection columns, which have a fixed width of 48px. Additionally, single icon action column types are set at a fixed width of 64px.

Table interface showing adjustable column widths, with options to save, reset, or cancel changes.

Column order

Column reordering is presented in a modal for a focused editing mode with explicit actions to save, reset, or cancel.

Modal window displaying stacked list of column reordering options for a data table, with 'Save', 'Reset table', and 'Cancel' actions available, as well as the ability to drag and drop columns to change their order.

Bulk editing

The bulk edit bar applies an action to all selected rows.

Write button labels from the user’s perspective. Use outcome-oriented verbs like “add” or “remove” because they tell the user exactly what will change as a result of their action.

For more guidance on which verb to use, check the This vs. That guidelines.

  • Use sentence case
  • No ending punctuation
  • Start with a [verb] and only add an object if the action alone is ambiguous
  • Aim for 1-3 words
Table with a list of smart TVs where items can be selected using checkboxes for bulk actions. A bulk edit bar appears above the table toolbar, offering options like delete, add coupon, and copy."

Pagination

Pagination is provided for all tables with more than 60 rows, allowing for easy navigation through the content by limiting the maximum number of rows per page. Don’t use endless scrolling for tables, as it can hinder user experience and make it difficult to manage or act on large data sets effectively.

Scrolled partial view of a data table on a mobile screen featuring pagination controls at the bottom for navigating through multiple pages of data.

Layer states

Hover is applied at the table row and cell levels for inner cell elements such as forms, dropdown, or buttons. Table focus is handled at the cell level. A disabled state can be applied at a row or cell level. See Interaction states for more details on layer state styling.

Cells detailing hover, focus, and disabled states.

Screen sizes

Orders page showing a filter bar with a data table underneath on a mobile device size screen. On the smaller screen size one and a half columns of data are visible.

Small

Seller dashboard orders page on a medium size screen showing a data table with filter bar on top.

Medium

Seller dashboard orders page on a large size screen showing a data table with filter bar on top and left hand tertiary navigation.

Large

Best practices

Color

Do use green to represent a positive trend for sales increasing or costs decreasing and red to represent a negative trend for sales decreasing or costs increasing. However, color cannot express this meaning alone. That is why we use the color in addition to an up or down arrow to represent this change. This provides contrast and conveys meaning for our color blind or low vision users.

Data table column displaying three sets of impressions data. The use of up and down arrows provides clear direction of trends for users with color vision deficiencies.

Don’t color cells as this is an issue for our color blind or low vision users. Color cannot express meaning alone.

Data table column displaying three sets of impressions data. The use of red and green as a background color for each row does not provide clear trend direction for users with color vision deficiencies.

Null

Do be descriptive when a field is empty or unknown.

Data table with three rows displaying order information. Second contains 'Pending' with no value indicated, suggesting an unknown or empty field.

Don’t use “--” to represent null or unknown fields.

Data table with three rows displaying order information. Second incorrectly contains '--' with no value indicated, which is unclear if the value is zero, null, or unknown.

Numeric alignment

Do align numbers to the right for improved scannability.

Data table with three rows displaying right aligned numeric price values.

Don’t left align numeric values.

Data table with three rows incorrectly displaying left aligned numeric price values.

Max content lines

Do keep content concise and to 4 lines max within a cell.

Data table cell correctly showing four rows of content.

Don’t exceeed more then 4 lines of content in a given cell.

Data table cell incorrectly showing six rows of content.

Headers

Column headers should be short, specific, and easy to scan

Column header copy, “order total”.

Don’t use generic labels as column headers.

Column header copy, “info”.

Specs

Data table with four columns and four rows of placeholder data showing specs: 24px for the header row, and 16px between selection checkboxes in the first row and the first column.