Design

FAQ

When to use a Card grid instead of a Table?

More than one layout type can be included in a DataView, but the default layout should be the one that prioritizes the property that best identifies the item. When deciding which layouts to support, follow these recommendations:

• Include a List layout with a Table when there are important item properties that are textual and may need to be compared. For example, a list of products, promotions, or orders.
• Include a Grid layout with Cards when there are important item properties that are visual. For example, app logos in a list of apps or thumbnails in a media gallery.

When to use the Bulk Actions component with a Table?

When it's possible to edit multiple items directly from the table, a Checkbox column should be included as the first column. The Bulk Actions component should appear when the merchant has checked at least one row. Read the Bulk Actions (opens in a new tab) documentation for more details.

When to use the DataView component with a Table?

Always use the DataView component with a Table. This component is essential for dealing with states and implementing additional components such as Search, Filters and Pagination. Read the DataView (opens in a new tab) documentation for more details.

When to include a Menu in each row?

• When rows are clickable, always add a Menu including a View details action with the same purpose as clicking the row, even if there are no other actions for the item.

• If the action is very important, it can be outside the Menu. For example, activating or deactivating an item such as SKU Bindings or approving or refusing a request such as Invoices.

• Destructive actions should always be inside a Menu.

• If the Table fits all the information and actions, or if the line can’t be clicked, there is no need to include a Menu.

What to avoid:

• Don’t include more than two actions outside the Menu on each Table row.

When to include rows that can be clicked?

• If there is a way to open a Modal or a Page to view or edit an item, trigger this action when merchants click the row.

What to avoid:

• Don’t open a Popover or Menu when a row is clicked. Only open the Menu if the merchant clicks the Menu directly.

When to include fixed columns?

Add fixed columns when merchants need to keep viewing the information that identifies the item, such as ID or Name, even during horizontal scroll.

When should a column be sortable?

• When a Name column exists, always allow it to be sorted alphabetically.
• Consider supporting sorting in all columns where the content has a clear order. For example, dates, texts and numbers can be sorted by ascending or descending order. Images, however, can’t be sorted.

What column type should I use for each property type?

The type of column depends on the property type that will be displayed. Common property types include:

• Name: Dedicated 1-line Text column or 2-line Text column along with ID or Description.

• Image: In left-to-right languages, the Image should always be displayed to the left of the Name in a Thumbnail column.

• ID: Dedicated 1-line Text column or 2-line Text column along with the Name.

• Description: 2-line Text column that includes both Name and Description.

• Tertiary actions: Menu.

• Secondary actions: Button.

• Bulk Actions: Checkbox.

• Status: Tag.

• Value or Price: Number.

• Creation or Update date: 1-line Text.

• Country or payment flag: Icon.

• Type of object: 1-line Text, with or without an Icon before it.

• Percentage value or tendency: Dedicated 1-line Number column or in a 2-line Number column along with the numeric value.

What to avoid:

• Don’t display columns with personal information, such as email addresses, personal names, addresses or phone numbers.

Where should a Table be positioned in a container?

Use the DataView (opens in a new tab) component to correctly position the Table. Read the documentation of this component for more details.

What should be the alignment of content in a Table?

Considering left-to-right languages, the content of cells and the label of each column should be left-aligned, with the exception of Number columns, where content should be right-aligned.

What should be the column width?

The column width should be specified in a fractional unit (opens in a new tab) (fr), which represents a fraction of the available space in the row. For example, the Name column can have the width set to 2 fr and the Status column can have the width set to 1 fr.

Besides representing column width in this responsive unit, it is important to set a minimum comfortable width in rem to avoid line breaks in tighter viewports.

What should be the order of columns?

The order should be defined based on research with merchants. However, the following recommendations should be considered:

• Position properties that identify list items first, such as ID and Name.

• Position the Menu (opens in a new tab) as the last column and immediately before it a tag with the item’s status, when it exists.

What should be the height of the table row?

The default height is 44px. The table row height should only use the larger 64px height when there are columns that occupy the additional space, such as an image or 2-line Text.

What to avoid:

Don't customize the table row height, for aesthetic and standardization reasons.

When to use a loading Table?

• Only use the loading state of the Table during the initial load of the Page or during Pagination.
• During a search, keep the previous results until the new ones load and don’t show the loading state of a Table.

What should be the default sorting of a Table?

The sorting should be defined based on research with merchants. In most cases in the Admin, the default sorting is based on the items’ creation date (from the most recent to the least recent), as in Products & SKUs, Brands and Orders listing pages. However, there are cases such as the Promotions listing page where the default sorting is by status.

What should be the column header labels?

• Write the label so that it describes the property type whose values are in the column.
• Use sentence case.
• Use short labels. Prefer two words maximum.

What to avoid:

• Don't write labels that vary a lot in length between options.
• Don't include redundant words. For example, use only Name instead of Product name.

What should be the actions for each row?

Row actions can be in Buttons or in a Menu, depending on their relevance. Read the Button (opens in a new tab) and the Menu (opens in a new tab) documentation for more information.

Conduct UX research with merchants to determine actions that need to be available. Common actions on Table rows include:

• View details
• Edit
• Delete
• Rename
• Duplicate
• Share
• Archive

Actions that exist in the Bulk Actions or on a details page should also be included in each row.

What to avoid:

• Don't include more than five actions for each row.

What should be the formatting of text in a cell?

• The text that best identifies items should use the $action1 typography token. For example, the Name or the ID when items don't have a Name.
• Percentage values and tendencies should use semantic colors to visually represent information.
• Descriptions and IDs (when there is a separate Name column) should use the $fg.secondary token.