When to use
- To organize content into sections that users need to switch between frequently.
- When sections are related and share the same context.
- To display mutually exclusive content without overwhelming the user.
- For navigation within a page or primitive (e.g., dashboards, settings, data views).
When to use something else
- Simple data filtering: use Segmented control or a filter Button with Menu.
- User must see multiple sections at once: keep one page and use Accordion or filters—not mutually exclusive Tabs.
- Binary on/off: use Switch.
Dos and don’ts
- Do use a minimum of two Tab buttons.
- Do be mindful of persistent and non-persistent CTAs when using Tabs. Content above Tabs should remain the same across Tabs.
- Don’t use for binary options.
- Don’t use Tabs for basic filtering functionality.
- Don’t be inconsistent with leading icon usage. If using in one, use them in all.
Placement & alignment
Placement:Tabs are typically placed at the top of a page or section, often within the main content area, Topbar, or side panels. Always place Tabs close to the content they control and ensure Tab placement is consistent across pages or flows. Alignment
- Tabs allow for a default and vertical alignment, which essentially shows or hides label padding on each tab Button. This is similar to how Buttons behave.
- Tabs can also be displayed in full width, where the spacing between tabs adjusts evenly allowing the primitive to fill the parent container’s width. Consider the surrounding content and container when deciding which to use. This is best used in side panels or when there are a lot of Tabs that take up the entire width of the container.
Behavior
- Exactly one tab panel is visible at a time for a given tab set; tab buttons update
aria-selected/ roving focus per implementation. - Content above the tab list should stay stable across tabs; don’t move primary CTAs in ways that disorient users when switching.
Often used with
Tab panels containing Data grid, forms, Cards, or Empty state; keep global page actions outside the tab panel when they must not move.Visual examples
The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.With icon
Add leading icons to tab labels when they help users scan sections quickly—for example, settings, data, or notification views.Size inheritance
Tab button size inherits from the tab list configuration—match the size to surrounding controls, such as smaller tabs in dense panels or larger tabs in primary navigation.With badge
Add a badge to a tab when a section has a count or status users should notice—for example, unread items, pending tasks, or new content.Decorative badge
Use a decorative badge for non-numeric indicators—for example, marking a tab as “New” or “Beta” without implying a specific count.Full width
Use full-width tabs when the tab list should span its container—for example, in a side panel or when each tab should share equal space across the available width.Icon only
Use icon-only tabs when space is limited and the icons are widely understood—always pair with tooltips and accessible names so meaning is clear.Orientation
Choose vertical or horizontal tab alignment based on layout—vertical tabs work well in side panels, while horizontal tabs suit page-level navigation.Interactive
Use interactive tab examples to verify keyboard navigation, focus management, and panel switching behave correctly in your implementation.Accessibility
Ensure tab buttons expose correctaria-selected state, roving focus works as expected, and each panel is associated with its tab for screen reader users.