Tabs
Tabbed content interface that switches between related content panels within the same page region. Reach for tabs when several panels of content share context but only one needs to be visible at a time - a specification sheet, a settings screen, or a mission briefing split into overview, crew, and timeline.
Usage
When to use
- Grouping related content into parallel panels
- Saving vertical space when content sections are mutually exclusive
- Settings, profile sections, or product detail breakdowns
When not to use
- Content users need to compare side-by-side
- Sequential steps - use a stepper or form pagination
- When users may want to print or search all panels at once - use headings with an accordion instead
Do
- Give each tab a short, scannable label
- Keep the number of tabs small enough to fit without scrolling
- Preserve the active tab state on reload where it makes sense
Don't
- Nest tabs inside tabs
- Hide primary navigation behind a tab
- Use tabs when content order matters (first, then, finally)
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
panels | array | - | Array of {title, content} panel objects. Each panel renders a tab button and a tabpanel. |
links | array | - | Optional array of custom label strings to override auto-generated tab labels from panel titles. |
tabs_id | string | - | Base for the generated tab and panel ids ("{tabs_id}-tab-{n}" / "{tabs_id}-panel-{n}"). Defaults to "tabs"; set a unique value when a page renders more than one tabs instance. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.solid | Fill | - | Filled surface; background and border rendered. |
.outline | Fill | - | Bordered surface; transparent background. |
.ghost | Fill | - | No surface; text or icon only. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.fill | Fit | - | Content stretches to fill the box, may distort (object-fit: fill). |
.fluid | Layout | - | Full-width, no max-width. |
.horizontal | Orientation | Yes | Children flow along the horizontal axis. |
.vertical | Orientation | - | Children flow along the vertical axis. |
.animated | Motion | Yes | Honors the animations option. |
.still | Motion | - | Forces motion off regardless of the option. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-tabs | Consumer | Yes | Marks the tabs root. Required for the JS to wire up the tablist, tabs, and tabpanels. |
Examples
Horizontal
Horizontal tab bar with underline indicator and panels below.
Auto-generated horizontal
Horizontal tabs generated automatically from each panel title.
Vertical
Tabs stacked on the left with panels on the right.
Auto-generated vertical
Vertical tabs generated automatically from each panel title.
Accessibility
- WCAG 2.2 AA
- Full keyboard support: Tab moves focus in and out of the tablist; Left/Right (or Up/Down for vertical) move between tabs; Home/End jump to first/last tab
- Only one tab at a time is reachable via Tab - arrow keys move within the tablist
- Active tab is programmatically indicated to assistive technology
- Each panel is labeled by its corresponding tab
Related
- accordion - alternative reveal pattern for sequential or searchable content