Tab

What is this?

Tab triggers allow merchants to navigate between up to five views of content that are in the same level of hierarchy.

Example

Panel 1

Panel 2

Id

Panel 1

Panel 2

Default selected id

Panel 1

Panel 2

Manual navigation

Panel 1

Panel 2

Usage

import {
  Tab,
  TabList,
  TabPanelList,
  TabPanel,
  useTabState,
} from '@vtex/admin-ui'

function Example() {
  const state = useTabState()

  return (
    <>
      <TabList state={state}>
        <Tab>Tab 1</Tab>
        <Tab>Tab 2</Tab>
      </TabList>
      <TabPanel state={state}>Panel 1</TabPanel>
      <TabPanel state={state}>Panel 2</TabPanel>
    </>
  )
}

TabList Props

Name	Type	Description	Required	Default
state	TabState	Tab state	✅	-
children	ReactNode	Tabs children	✅	-

Tab Props

Name	Type	Description	Required	Default
id	string	Tab's id	🚫	-

TabPanelList Props

Name	Type	Description	Required	Default
children	ReactNode	Component children	✅	-
state	TabState	Tab state	✅	-

TabPanel Props

Name	Type	Description	Required	Default
id	string	The same id as the correspondent Tab's id	🚫	-

useTabState

Hook parameters

Name	Type	Description	Required	Default
defaultSelectedId	string	The current selected tab's id	🚫	-

TabStateReturn

Properties returned by the useTabState hook:

Name	Type	Description	Required	Default
selectedId	string	The current selected tab's id	🚫	-
select	() => void	Moves into and selects a tab by its id	🚫	-
first	() => void	Moves focus to the first item	🚫	-
last	() => void	Moves focus to the last item	🚫	-
next	() => void	Moves focus to the next item	🚫	-
previous	() => void	Moves focus to the previous item	🚫	-

Accessibility

Each TabPanel should have an id correspondent to the id of its Tab.
Every TabList should have the aria-label defined to guarantee accessibility.

Components

When to use a Select Inline, Filter, Button, or Radio Group instead of a Tab?

• Choose the Select Inline component when there are over five views, and they should be less prominent.
• Choose the Filter component when there is a complete set of data that can be narrowed according to specific criteria to help find relevant information.
• Choose the Button component to lead to a separate page when the content should not be in the same hierarchy level.
• Choose Radio Group component to allow merchants to make a single choice that fills in information that will be submitted in a form.

When to separate the content of a container in different views?

• Use Tabs to navigate between distinct but related content that is in the same level of hierarchy.
• Use Tabs to separate the general from the specific, when there’s a lot of content. For example, in a product form, there can be a General view and an SKUs view.

What to avoid:

• Don’t use Tabs for content that is related to different main jobs. For example, Contracts should not be on the same page as Invoices, since they won’t be needed at the same time.
• Don’t use Tabs to indicate progress. The merchant should always be able to alternate between views freely.
• Don’t use Tabs for content that is usually compared. For example, order items should not be separate from order total value.
• Don’t use Tabs in containers that are inside a page which already uses Tabs.
• Don't reload the page when switching between tabs.

Position

Where should a Tab be positioned in a container?

Considering left-to-right interfaces, follow these recommendations:

• Position Tabs in the header of a container, below an existing title and above the content that can be alternated.
• Align Tabs to the left.

Behavior

Which Tab should be preselected?

The first Tab should always be preselected, to simplify the flow of an user who wants to go through all Tabs and avoid confusion.

Content

What should be the label of a Tab?

• Write the label so that it describes the content of the view.
• Use sentence case, but capitalize proper nouns.
• Use short labels. Prefer two words maximum.

What to avoid:

• Don't write Tab labels that vary a lot in length between options.
• Don't use personal pronouns. For example, write Application keys instead of My application keys.
• Don't include redundant words. For example, use only Products and Categories instead of Product permissions and Category permissions.

When to use icons in a Tab?

Never use icons in a Tab, even when there is a label next to them. The main reasons for this are maintaining consistency across the product, keeping the interface visually simple and avoiding confusion when a Tab’s subject is difficult to represent through an icon.

What should be the order of Tabs?

Order Tabs using one of the following criteria:

• General to specific.
• Most to least frequently used.
• Alphabetical order.

• What is this?
• Example
• Id
• Default selected id
• Manual navigation