Tabs

Example

Patterns

Collections

Tabs implements react-stately collection components, <Item>.

Static collections, seen in the example above, can be used when the full list of tabs is known ahead of time.

Dynamic collections, as shown below, can be used when the tabs come from an external data source such as an API call, or update over time. Providing the data in this way allows Tabs to cache the rendering of each item, which improves performance.

Keys and IDs

Dynamic collections provide an iterable list of items to the picker. Each item accepts a unique key prop, which is passed to the onSelectionChange handler to identify the selected item. If the item objects contain an id property it is used automatically and a key prop is not required.

Selection

Setting a selected item can be done by using the defaultSelectedKey or selectedKey prop. The selected key corresponds to the key of an item, where "id" is used by default.

See the react-stately selection docs for more information.

Controlled

Use the selectedKey the control the value of the picker and watch for changes with the onSelectionChange handler, which accepts the selected item’s key as its only argument.

Uncontrolled

Use the defaultSelectedKey prop for uncontrolled cases.

Slots

Icons can be added as children of an item, to better communicate intent.

Extra visual details increase the cognitive load on users. Include additional elements only when it improves clarity and will contribute positively to the understanding of an interface.

Props

Prominence

The prominence of the tabs influences their visual weight. Tabs with “low” prominence have a more subtle indicator that shows the selected tab item. These should be used as sub-level navigation or for containers.

Disabled

Provide disabledKeys to disable individual tabs. This state can be used to maintain layout continuity and to communicate that the tab item may become available later.

You can also disable the entire Tabs component with the isDisabled prop. However this is uncommon and would only be appropriate, for instance, during a busy state of the application.

Orientation

Vertical tabs should be used when horizontal space is more generous and when the list of sections is greater than can be presented to the user in a horizontal format.

Accessibility

While an aria-label is not explicitly required for a tab list, Tabs should be labeled using a aria-label in the absence of an ancestor landmark. This will prevent screen readers from announcing non-focused tabs, allowing for a more focused experience.

Best practices

Tabs are used to group different but related content, allowing users to navigate views without leaving the page. They always contain at least two items and one tab is active at a time. Tabs can be used in full page layouts or in components such as dialogs or cards.

Tabs should:

• •
  Represent the same kind of content, such as a list-view with different filters applied. Don’t use tabs to group content that is dissimilar.
• •
  Not force users to jump back and forth to do a single task. Users should be able to complete their work and find what they need under each tab.
• •
  Not be used for primary navigation.