Tabs organise content across screens, data sets and interactions at the same level of hierarchy. A tab bar lets the user move between groups of related content without leaving the page. For content that must be read in order, use steps instead.
Every example on this page is the real component, not a picture. Figma: Tab items, Tab bar sizes, Tab info.
Click a tab or use the arrow keys, Home and End. Primary tabs sit at the top of a content page; Secondary tabs sit below them, inside a content area. Large and Medium look the same on desktop; Small is smaller.
Tabs organise content across screens, data sets and interactions at the same level of hierarchy. A tab bar lets the user move between groups of related content without leaving the page. For content that must be read in order, use steps instead.
Tabs come as Primary and Secondary, in three sizes, with a label, a label and an icon, or an icon only, and with an optional status dot or number. A bar either switches panels on the same page (content tabs) or links to other pages (navigation tabs).
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use tabs. Specifications holds the values: tokens, sizes, states and requirements. Code shows how to add a tab bar to a page.
Use tabs to organise content at the same level of hierarchy. They control the region shown below them. Use them to:
Answer up to five questions. The answer shows the type, why, and a live example you can try in the Playground.
| Primary | Secondary | |
|---|---|---|
| Where | At the top of a content page. | Below the primary tabs, if the page has any. Inside the area it controls. |
| What it does | Shows the main content destinations. It is sub-navigation when the main navigation needs more levels, or top-level navigation where there is none. | Separates related content inside an area and establishes hierarchy. |
| What it controls | The page, or the part of the site, below the bar. | The region shown below the bar. |
| Examples | The My Pages account menu. A campaign page. | A card or a sheet. An information pane. A carousel with categories. The sections of one page: an article with titles, a campaign page or a brand page. |
| Number of tabs | Two or more, no upper limit: the bar scrolls sideways. | Two or more, no upper limit. A page with many sections, or sections that are added over time, is a good fit: the bar scrolls and keeps the current tab in view. |
| How many bars | One bar per page. | One per area. Under the primary tabs when the page has them. Never more than two levels. |
| Look | 24px between the tabs. The line is as wide as the label and 3px when active. | 16px padding on each side of a tab, no gap. The line is wider than the label and 2px when active. |
Use a stepper (steps) when the user goes through content in a fixed order. Use eco-pill-segment-control to switch between two to four views or filters of the same content (a fixed, small number: with more options, or a number that can grow, use tabs), a button group for joined options in a toolbar, and eco-radio for a choice that is submitted.
Secondary tabs go below primary tabs, never above, and a page does not nest more than two levels.
Tab labels sit in one row. A few short labels are read at a glance; long labels make the bar scroll sideways and hide tabs.
| The user… | Use |
|---|---|
| moves between pages or sections at the same level | Tabs |
| moves between the sections of one page, however many there are or will be added | Secondary tabs, tab-bar--page |
| switches between a fixed 2–4 views or filters of the same content | Pill segment control |
| chooses between a few joined options in a toolbar | Button group |
| goes through content in a fixed order | Steps (stepper) |
| makes a choice that is submitted | Radio |
aria-label.div.tabs.css.aria-label.Primary tabs are placed at the top of a content page, as sub-navigation when the main navigation needs more levels, or as top-level navigation where there is none (for example campaign pages). The line spans the label, 24px between tabs. Secondary tabs are always placed below primary tabs, if any. They separate related content inside an area (a card, a sheet, an information pane, sections on one page). Each tab has 16px side padding, so the line is wider than the label.
Label only, label with an icon above it, or icon only. Use standalone icons only when they are globally well known, and give each an aria-label.
A red dot marks something new in a tab. A red number badge says how many. Both sit after the label, 4px away. On an icon-only tab the dot sits at the icon’s top right. An icon can also lead the label: 24px, or 20px on Small below 769px.
Background Colored in Figma: the hover line is surface-40 instead of surface-10, so it stays visible on grey. Add .tab-bar--on-grey.
The active line is black by default. Where a product uses its accent colour, set --tab-line-active on the bar. Swedol uses --color-accent-default; Tools is a primitive in the package (--color-primitive-color-brand-tools-accent-brand). Primary and Secondary tabs, content tabs and link tabs all follow it; the grey hover line does not change. Click a tab to see the line slide in the accent colour.
Tab labels appear in one row. Scrollable tabs are preferred when the titles do not fit: the bar scrolls sideways and the divider line runs the full width. Drag or scroll the bar below.
Secondary tabs can navigate a whole page. Each tab is a link to a section: the bar sticks to the top, the line follows the section in view, and a click scrolls to the section. The page can have as many sections as it needs: the bar scrolls sideways and keeps the current tab in view. Add tab-bar--page, and scroll the page below or click a tab.
Large, Medium and Small. Below 769px the labels are 16/16 (Large, Medium) and 14/14 (Small); from 769px 18/18 and 16/16. Large and Medium differ only in the gap to the line on mobile. Measurements are under Sizes in Specifications.
Primary tabs go at the top of a content page. Secondary tabs go below them, inside the content area they control. The bar is as wide as its container.
The bar scrolls sideways with the scrollbar hidden, and the active tab is scrolled into view. The divider runs the full width. The overflow “more” button is not built yet.
Labels are uppercase Breuer Condensed. The active tab has a black label and a black line; hover gives a grey line. Token names and values are under Design Tokens in Specifications.
A click on a tab, or arrow-key focus, opens that tab. On content tabs the active line slides to the clicked tab. On navigation tabs the line slides across the page change.
With tab-bar--page the tabs are links to sections of the page. The line follows the section in view as the page scrolls. A click scrolls to the section (150 to 450 ms by distance, ease-decelerate-generic, instant under reduced motion), moves focus to it and adds the #hash to the address. The number of sections is not limited. Details are under Behavior in Specifications.
Hover gives a grey 3px line and greys the label and the icon. Focus is a 2px ring around icon and label, on an enabled or an active tab alike; the line stays visible below it. All states are listed under States in Specifications. Figma has no disabled state, so none is built.
The sliding line uses duration-medium-2 with ease-standard and is off under reduced motion. Details are under Motion in Specifications.
All requirements are listed under Accessibility Requirements in Specifications.
Tab moves into the bar. Left and Right switch tab (they wrap), Home and End go to the first and last. A tab opens as soon as it is focused. tabs.js does this.
Content tabs use role="tablist", role="tab" with aria-selected and aria-controls, and role="tabpanel" with aria-labelledby. Navigation tabs are links in a nav, with aria-current="page" on the current one. An icon-only tab needs an aria-label.