Tabs

Choosing navigation⁠link

Two components show a row of destinations to choose from. Each suits a different job:

Two jobs belong elsewhere. Moving through pages of results is a paginator, and a list of commands is a menu.

Choosing a variant⁠link

Two kinds of tab set how many levels a bar shows:

• Primary tab: the main sections of a content area, such as Overview, Specs, and Reviews on a product page. It stacks an icon above the label in a 64-pixel tab, or places it beside the label in a 48-pixel tab with inline-icon.
• Secondary tab: the parts of one section, such as Newest and Top rated under Reviews. Its indicator spans the full width of the tab, and an icon sits beside its label.

Built in⁠link

• active-tab-index and activeTab set and read the selected tab from code.
• auto-activate selects a tab as soon as an arrow key focuses it, instead of waiting for Enter or Space.
• beforechange fires before the selection moves and can be canceled; change fires after.
• Tabs that overflow the bar scroll sideways, with no scrolling code to write.
• The arrow keys, Home, and End move focus between tabs, and Left and Right swap in right-to-left layouts.
• The active indicator slides between tabs, and moves at once under reduced motion.
• A tab sets has-icon and icon-only for itself from what it holds, so you leave both unset in a browser.

Using tabs well⁠link

• Put primary tabs at the top of a content area, use secondary tabs one level below, and stop at two levels.
• Write each label in one or two words, and let it show in full instead of truncating it.
• Give every tab in a bar an icon, or none of them.
• Use tabs for the views of one content area, and a navigation to move between an app's top-level destinations.
• Leave the active indicator in place: a change of color alone does not mark the selected tab.

These rules follow Material 3 Expressive's guidance for tabs, on material.io.

Tab styles⁠link

A primary tab, cw-primary-tab, shows an icon above its label, or beside it with inline-icon. A secondary tab, cw-secondary-tab, shows a label alone under a full-width indicator. The Overview's Choosing a variant says when to use each.

Icons⁠link

A tab's icon goes in its icon slot. A primary tab stacks it above the label, and inline-icon puts it beside the label, which gives a shorter tab that takes more width. A secondary tab always shows it beside the label. Use one style across a bar, and turn the switch to compare the two.

A tab sets has-icon and icon-only for itself from what it holds, so set them only when rendering on the server.

Icon only⁠link

A tab with an icon and no label sizes itself to the icon. Give it an aria-label, as the demo does; Names and states says why.

Panels⁠link

The tab bar sets active on the selected tab and fires change, and that is all: it neither shows nor hides content. Show the panel for the selected tab yourself, as this demo does from the index the tab bar is bound to.

Tie each tab to its panel for assistive technology with the attributes that Names and states lists, as the demo does.

Selected tab⁠link

active-tab-index selects a tab by its position, counting from 0, and activeTab reads the selected tab. An index outside the range of tabs is ignored, and so is setting activeTab to null. If the selected tab is removed, the first tab is selected.

The first tab is selected when the bar renders and active-tab-index is unset. To start the bar on another tab, set active on that tab and let the bar move it after that. selected is a deprecated alias of active.

Automatic activation⁠link

By default the arrow keys move focus and Enter or Space selects the focused tab, so a reader can scan the labels without loading each view. auto-activate makes the arrow keys select as well as move focus. Turn it on only when showing a view is instant and cheap.

Change events⁠link

beforechange fires first, when a click, a key press, or an assignment to active-tab-index is about to move the selection, and detail.activeTabIndex names the tab it is moving to. Call preventDefault() on it to leave the selection where it is. change fires after the move and cannot be canceled; it is the event a binding of active-tab-index follows, so the demo below binds the index rather than listening for it.

The automatic selection of the first tab raises neither event.

tabs.addEventListener("beforechange", (event) => {
  if (hasUnsavedEdits) {
    event.preventDefault();
  }
});

Overflow⁠link

When the tabs do not fit, the bar scrolls sideways and shows an edge shadow where more tabs lie beyond. There is nothing to configure. Keep the labels short enough that the most important tabs are visible without scrolling.

Two levels⁠link

Primary tabs sit at the top of a content area and secondary tabs subdivide one of its sections. Use one tab bar for each level, and show the secondary bar only inside the panel that owns it. Stop at two levels.

Names and states⁠link

The tab bar is announced as a horizontal tab list and each tab as a tab; both follow the WAI-ARIA Authoring Practices: Tabs pattern.

• Give the bar an aria-label. It names the tab list.
• A tab's accessible name is its label text. An icon-only tab has no name, because the icon is hidden from assistive technology, so give that tab its own aria-label.
• The selected tab is announced as selected, and the others as not selected.
• The tab bar does not link tabs to panels or hide anything. Give each tab aria-controls, give each panel role="tabpanel" and aria-labelledby, and hide the panels that are not selected, as Panels shows.
• A tab has no disabled, href, or badge. For links between destinations, use Navigation.

Keyboard and focus⁠link

The component handles all of these keys itself. The arrow, Home, and End keys do nothing with fewer than two tabs, and Up Arrow and Down Arrow do nothing at any count.

• The bar is a single Tab stop: Tab enters it at the selected tab, and returns there after focus leaves.
• The arrow keys move focus without selecting. With auto-activate, a tab is selected as soon as it takes focus.
• A focus ring appears inside the tab on keyboard focus, and not on a pointer click.

Pointer and touch⁠link

• By default a tab is 48 pixels tall, or 64 pixels with an icon stacked above its label, and the tabs share the width of the bar. Both are well above the 24 by 24 pixels that WCAG 2.5.8 asks for.
• A press anywhere inside a tab, on its icon or its label, selects that tab.

Display settings⁠link

• In forced colors, the active indicator uses the system text color.
• Under reduced motion, the active indicator moves between tabs at once instead of sliding, and the bar scrolls without smooth scrolling.
• In a right-to-left layout, Left Arrow moves to the next tab and Right Arrow to the previous one.

Standards⁠link

With its defaults, the tab bar meets three WCAG 2.2 success criteria:

• 2.1.1 Keyboard (A)
• 2.4.7 Focus Visible (AA)
• 2.5.8 Target Size (Minimum) (AA)

Three more depend on how you use it:

• 1.1.1 Non-text Content (A): give an icon-only tab an aria-label, and give a slotted image an alt.
• 1.3.1 Info and Relationships (A): link each tab to its panel with aria-controls, role="tabpanel", and aria-labelledby.
• 4.1.2 Name, Role, Value (A): give the bar an aria-label, and give an icon-only tab its own aria-label.