Table

What is this?

Table containers allow merchants to view a vertical list of items with property values and related actions.

Composition

The Table is designed to easily integrate with other components to create the view. You must understand the concept of the DataView Pattern before reading this section.

Anatomy

Normally you will encounter Table as the data-rendering part of the data-view, for example:

DataView
|__ DataViewHeader
|   |__ Search
|   |__ Toolbar
|   |   |__ Button
|   |__ Pagination
|
|__ Table
    |__ .Head
    |   |__ .Cell
    |__ .Body
        |__ .Row
            |__ .Cell

Name	Brand	Price	Status
Wooden Eyeglasses	Revolution	$42.14	Inactive
Brazil Straw Hat	Pathway	$38.52	Inactive
Striped Beach Short	Desire Spirit	$23.49	Inactive

Search Form

Example using the Search component to filter the data.

Name	Brand	Price	Status
Wooden Eyeglasses	Revolution	$42.14	Inactive
Brazil Straw Hat	Pathway	$38.52	Inactive
Striped Beach Short	Desire Spirit	$23.49	Inactive

Toolbar

Example using the Toolbar component.

Name	Brand	Price	Status
Wooden Eyeglasses	Revolution	$42.14	Inactive
Brazil Straw Hat	Pathway	$38.52	Inactive
Striped Beach Short	Desire Spirit	$23.49	Inactive

Pagination

Example using the Pagination component.

1 — 5 of 100

Name	Brand	Price	Status
Tasty Soft Salad	Pathway	$377.00	Inactive
Awesome Concrete Shirt	Traction Race	$982.00	Inactive
Sleek Metal Fish	AeroSmart	$693.00	Inactive
Refined Concrete Chips	Desire Spirit	$149.00	Inactive
Incredible Fresh Tuna	Traction Race	$293.00	Inactive

Reacting to DataView status

By dispatch the setStatus function of the DataView, the Table reacts to it.

Name	Brand	Price	Status
Wooden Eyeglasses	Revolution	$42.14	Inactive
Brazil Straw Hat	Pathway	$38.52	Inactive
Striped Beach Short	Desire Spirit	$23.49	Inactive

Examples

This section presents a series of examples that may be useful.

Filters

Displaying filters and filtering data

Name	Brand	Price	Status
Ergonomic Rubber Keyboard	Quality Prints	$906.00	Active
Handcrafted Plastic Soap	Traction Race	$164.00	Active
Tasty Wooden Chips	AeroSmart	$899.00	Active
Gorgeous Plastic Soap	Desire Spirit	$233.00	Inactive
Rustic Steel Chips	Desire Spirit	$170.00	Active
Tasty Rubber Soap	Pathway	$511.00	Active
Rustic Steel Sausages	AeroSmart	$492.00	Inactive
Sleek Fresh Bacon	AeroSmart	$769.00	Active
Sleek Rubber Car	AeroSmart	$647.00	Inactive
Licensed Frozen Mouse	Revolution	$794.00	Active
Handcrafted Concrete Chair	Traction Race	$209.00	Active
Handcrafted Soft Mouse	Pathway	$855.00	Inactive
Unbranded Wooden Sausages	Desire Spirit	$581.00	Inactive
Incredible Soft Cheese	Desire Spirit	$872.00	Active
Sleek Soft Fish	Traction Race	$337.00	Active

Topbar

Mixing the concepts of Search, Toolbar and Pagination

1 — 5 of 100

Name	Brand	Price	Status
Sleek Cotton Cheese	Pathway	$513.00	Inactive
Tasty Cotton Tuna	Revolution	$955.00	Inactive
Sleek Granite Salad	Quality Prints	$891.00	Inactive
Small Cotton Hat	Traction Race	$123.00	Inactive
Licensed Soft Salad	Traction Race	$741.00	Inactive

Data fetching

Example with a simulated data fetching

Name	Brand	Price	Status
			__table_skeleton-0__
			__table_skeleton-1__
			__table_skeleton-2__

Selectable row

Example with selectable rows

	Name	Brand	Price	Status
	Wooden Eyeglasses	Revolution	$42.14	Inactive
	Brazil Straw Hat	Pathway	$38.52	Inactive
	Striped Beach Short	Desire Spirit	$23.49	Inactive

Fixed columns

It is possible to set columns to be fixed when scrolling horizontally. You just need to set the column prop fixed to true.

Name	ID	Label	Brand	Price	Status
Wooden Eyeglasses	495953	Apparel & Accessories	Revolution	$42.14	Inactive
Brazil Straw Hat	429048	Apparel & Accessories	Pathway	$38.52	Inactive
Striped Beach Short	495954	Apparel & Accessories	Desire Spirit	$23.49	Inactive

Usage

import {
  Table,
  TBody,
  TBodyRow,
  TBodyCell,
  THead,
  THeadCell,
  useTableState,
} from '@vtex/admin-ui'

const columns = createColumns([
  {
    id: 'productName',
    header: 'Product name',
  },
  {
    id: 'inStock',
    header: 'In Stock',
  },
  {
    id: 'price',
    header: 'Price',
  },
  {
    id: 'skus',
    header: 'SKUs',
  },
])

function Example() {
  /**
   * The hook returns the Table state
   */
  const { data, getBodyCell, getHeadCell, getTable } = useTableState({
    /**
     * Columns shape, read more about it on the rendering section
     */
    columns,
    /**
     * List of items to render
     */
    items: [
      {
        id: 1,
        productName: 'Orange',
        inStock: 380,
        skus: 0,
        price: 120,
      },
    ],
  })
  /**
   * You must use the `state` prop so that your Table comes to life
   * This is the only prop that is required
   */
  return (
    <Table {...getTable()}>
      <THead>
        {columns.map((column) => (
          <THeadCell {...getHeadCell(column)} />
        ))}
      </THead>
      <TBody>
        {data.map((item) => {
          return (
            <TBodyRow
              key={item.id}
              onClick={() => alert(`Item: ${item.productName}`)}
            >
              {columns.map((column) => {
                return <TBodyCell {...getBodyCell(column, item)} />
              })}
            </TBodyRow>
          )
        })}
      </TBody>
    </Table>
  )
}

State

The state hook useTableState contains all business logic needed for the component.

useTableState

Name	Type	Description	Required	Default
columns	Column<T>[]	Table column spec	✅	-
status	DataViewStatus	Related DataView status	🚫	-
context	ResolverContext	Resolver context	🚫	-
items	T[]	Table items	🚫	[]
length	number	Expected items length, this will also control the number of skeleton items	🚫	5
sort	UseTableSortParams<T>	useTableSort hook params	🚫	-

It returns an object with the following types:

export interface UseTableStateReturn<T> {
  /**
   * Collection rendered while loading
   */
  skeletonCollection: T[]
  /**
   * Resolves the cell content
   */
  resolveCell: (args: ResolverCallee<ResolveCellArgs<T>>) => ReactNode
  /**
   * Resolvers the header content
   */
  resolveHeader: (
    args: ResolverCallee<ResolveHeaderArgs<T>>
  ) => ResolveHeaderReturn
  /**
   * Items to render
   */
  data: T[]
  /**
   * Grid columns
   */
  columns: Array<TableColumn<T>>
  /**
   * Current sorting state
   */
  sortState: UseSortReturn
  /**
   * Table ref
   */
  tableRef: RefObject<HTMLTableElement>
  /**
    TBody cell props
  */
  getBodyCell: (
    column: TableColumn<T, BaseResolvers<T>>,
    item: T
  ) => TableBodyCellProps<T>
  /**
    THead cell props
  */
  getHeadCell: (
    column: TableColumn<T, BaseResolvers<T>>
  ) => TableHeadCellProps<T>
  /**
    Table props
  */
  getTable: () => TableProps<T>
  /**
  DataView related status
  */
  status: DataViewStatus
}

Rendering

The main objective of Table is to provide a flexible render to support any kind of data type.

Attribute	Type	Description	Required
id	string	String that defines the property name that the column represents.	✅
header	((column: Column<T>) => ReactNode), or string	Controls the title which appears on the table Header. It can receive either a string or an element.	🚫
accessor	((item: T) => ReactNode), or string	Defines how to access a property	🚫
resolver	R	Resolvers api Will select the plain resolver by default	🚫
width	number	Defines a fixed width for the specific column. Receives either a string or number. By default, the column's width is defined to fit the available space without breaking the content.	🚫
sortable	(a: T, b: T) => number	Defines if that column is sortable or not, passing true to this prop won't sort items by itself, the sorting will still need to be handled using the sort prop inside the StatelessTable sort prop. Check Sorting	🚫
compare	boolean	The function provided to handle the sorting of this column of the table, if this function is provided the table items will be sorted based on this function result. Check Sorting	🚫

Accessor

Some properties may be nested within objects and arrays. The accessor properties provide an easy way to access those.

Name	Brand	Price	Status
Wooden Eyeglasses	Revolution	$42.14	Inactive
Brazil Straw Hat	Pathway	$38.52	Inactive
Striped Beach Short	Desire Spirit	$23.49	Inactive

Resolvers

Resolvers are rendering functions that target a specific data type. The main usage is to render the same data types consistently along with admin applications.

Render function

All resolvers accept a render function, that returns a component. It controls the data rendering, which may be treated by the resolver or not.

{
  type: 'resolver name',
  /**
   * You have 3 render props here:
   * { item, data, context }
   */
  render: function Render({ item, data, context }) {
    return <></>
  }
}

Name	Type	Description
item	T	the item displayed for the row
data	unknown	extracted column data from the item, you need to cast it before use
context	{ loading: boolean }	relevant global information about the table current state

Root

This is the parent of all other resolvers. It does not treat the data at all - even the loading state is completely up to you. Use it if you want complete control over what's being rendered on the cell, and don't mind the complexity that it brings.

Name	Status	Price	Brand
Wooden Eyeglasses	Inactive	$52.14	Revolution
Brazil Straw Hat	Inactive	$49.52	Pathway
Striped Beach Short	Inactive	$53.59	Desire Spirit

Name	Type	Description	Required
type	root	Root resolver type	✅
render	(props: ResolverRenderProps<null, T>) => ReactNode	Resolver render function	✅

Plain

The plain resolver is the default for all columns. It means that if you don't select a resolver, this is what you're rendering. It should be mainly used to render raw data like strings or numbers that don't need treatment.

Product name	ID	Brand
Wooden Eyeglasses	495953	Revolution
Brazil Straw Hat	429048	Pathway
Striped Beach Short	495954	Desire Spirit

Name	Type	Description	Required
type	plain	Plain resolver type	✅
render	(props: ResolverRenderProps<ReactNode, T>) => ReactNode	Resolver render function	🚫

Text

The text resolver should be mainly used to render a text and an optional description just below it. For descriptions that are too long, it is possible to truncante it by setting the overflow prop. This resolver must be used on the name column of the table.

Name	Revenue
OrangeAn orange is a fruit of various citrus species in the family Rutaceae (see list of plants known as orange);	$1,223.49 30.91%
LemonThe lemon (Citrus limon) is a species of small evergreen trees in the flowering plant family Rutaceae, native to Asia, primarily Northeast India (Assam), Northern Myanmar or China	$257.36 78.62%
TomatoThe tomato is the edible berry of the plant Solanum lycopersicum,[1][2] commonly known as the tomato plant.	$742.19 0.00%

Name	Type	Description	Required	Default
type	text	Text resolver type	✅	-
columnType	name or text	Column text type	🚫	text
mapText	(item: T) => ReactNode	The map function which returns the text to be rendered	✅	-
mapDescription	(item: T) => ReactNode	The map Function which returns the description to be rendered	🚫	-
overflow	ellipsis or auto	It specifies how overflowed text should be signaled to the user.	🚫	-
render	(props: ResolverRenderProps<ReactNode, T>) => ReactNode	Resolver render function	🚫	-

Menu

The menu resolver should be used when you want to easily render a Menu component and a set of actions.

Name	Brand	Price	Status
Wooden Eyeglasses	Revolution	$42.14	Inactive
Brazil Straw Hat	Pathway	$38.52	Inactive
Striped Beach Short	Desire Spirit	$23.49	Inactive

Name	Type	Description	Required	Default
type	menu	Menu resolver type	✅	-
actions	MenuAction[]	A set of actions to be rendered as MenuItems	✅	-
render	(props: ResolverRenderProps<JSX.Element, T>) => ReactNode	Resolver render function	🚫	-

MenuAction

Name	Type	Description	Required	Default
label	string	MenuItem label	✅	-
onClick	(item: T) => void	MenuItem onClick handler	✅	-
icon	ReactNode	MenuItem icon	🚫	-
disabled	boolean	Whether the MenuItem is disabled or not	🚫	false
critical	boolean	Whether the MenuItem is critical or not	🚫	false

Currency

Price	عملة	价格	Preço
$1,242.14	‏١٬٢٤٢٫١٤ ر.س.‏	¥1,242.14	R$ 1.242,14
$738.52	‏٧٣٨٫٥٢ ر.س.‏	¥738.52	R$ 738,52
$23.49	‏٢٣٫٤٩ ر.س.‏	¥23.49	R$ 23,49

Name	Type	Description	Required
type	currency	Currency resolver type	✅
locale	string	Currency locale	✅
currency	string	Currency type	✅
render	(props: ResolverRenderProps<string, T>) => ReactNode	Resolver render function	🚫

Date

Date	Data	تاريخ	日期
September 14, 2022	14 de setembro de 2022	14 سبتمبر 2022	2022年9月14日
July 1, 2002	1 de julho de 2002	1 يوليو 2002	2002年7月1日
March 21, 2013	21 de março de 2013	21 مارس 2013	2013年3月21日

Name	Type	Description	Required
type	date	Date resolver type	✅
locale	string	Date locale	✅
options	Intl.DateTimeFormatOptions	Date options	🚫
render	(props: ResolverRenderProps<string, T>) => ReactNode	Resolver render function	🚫

Image

	Name	Brand	Price	Status
	Wooden Eyeglasses	Revolution	$42.14	Inactive
	Brazil Straw Hat	Pathway	$38.52	Inactive
	Striped Beach Short	Desire Spirit	$23.49	Inactive

Name	Type	Description	Required
type	image	Image resolver type	✅
alt	string	HTML img alt	🚫
render	(props: ResolverRenderProps<JSX.Element, T>) => ReactNode	Resolver render function	🚫

Bulk

The bulk resolver should be used when you want to add a bulk actions to the table. It is a easier way of using the BulkActions component within the Table. When using this resolver there are two things you should follow in order to work properly: wrap the Table component with the SelectionTree component and avoid adding more than 25 items per page.

1 — 5 of 100

	Name	Brand	Price	Status
				__table_skeleton-0__
				__table_skeleton-1__
				__table_skeleton-2__
				__table_skeleton-3__
				__table_skeleton-4__

Name	Type	Description	Required
type	bulk	Bulk resolver type	✅
state	BulkActionsState<T>	The useBulkActions hook state return	✅
render	(props: ResolverRenderProps<ReactNode, T>) => ReactNode	Resolver render function	🚫

Selection

The selection resolver should be used when it is necessary to have rows selectable and to have control of which rows are selected.

ReferenceError: data is not defined

Name	Type	Description	Required
type	selection	Selection resolver type	✅
mapId	`mapId: (item: T) => string	number`	The map function which returns the id to be used by the checkbox	🚫
render	(props: ResolverRenderProps<ReactNode, T>) => ReactNode	Resolver render function	🚫

Sorting

To use the base sorting configuration, that matches the majority of use cases, you just need to pass the compare function to the columns that you want to sort by. Two params are accepted, representing two items - you must return a boolean that proves their equality.

type Compare = (a: T, b: T) => boolean

Configuration

The following example allows ordering by name, creation and price. By using the sort property within useTableState you can configure the sorting to match specific use cases.

Name	Created date	Price
Wooden Eyeglasses	Sat Jun 29 2024	$42.14
Brazil Straw Hat	Thu May 09 2024	$38.52
Striped Beach Short	Mon Sep 16 2024	$23.49

initialValue

• Defines the table's initial sorting value. { order?: 'ASC' | 'DESC', by?: string }

• The order prop is related to the sorting order and by indicates which column is being sorted, this value should be the id of the column.

directions

• Defines the sorting order of the table.
• It accepts an array with ASC and DESC as possible values. You can pass an array with one or two sorting directions. If you pass an array with only one sorting direction the table will only sort in one direction.

reducer

• Receives the reducer that will be used inside of the useReducer that handles the sorting state, it is not required and if not provided the default reducer function will be used.

• The reducer function is called with the current sort state { order?: SortOrder, by?: string } and the sorting action { type: SortOrder | 'RESET', columnId?: string }.

callback

• Receives a function that will be fired when the user clicks the table header cell of a column.

• This function is called with an object containing the current sort state, the dispatch of the current useReducer that handles the sorting state, the column id of the column that was clicked, and the current sort directions being used.

Components

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 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 documentation for more details.

Variants

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.

Position

Where should a Table be positioned in a container?

Use the DataView 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 (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 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.

Behavior

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.

Content

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 and the Menu 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.

• What is this?
• Composition
  • Anatomy
  • Search Form
  • Toolbar
  • Pagination
  • Reacting to DataView status
• Examples
  • Filters
  • Topbar
  • Data fetching
  • Selectable row
  • Fixed columns