Version: 3.5.13

Tabs

Tabs organize content into related sections that users can navigate between. The Tab component contains TabItem components that represent individual tab options.

Overview

Tabs provide a way to organize and navigate between related content sections. The Tab component acts as a container for TabItem components, which represent individual tab options. TabItems can be displayed in different states, sizes, and styles to fit various use cases.

All tab styles are built using design tokens, ensuring consistency across themes and hues. Use the interactive playground below to explore TabItem variants, and see the usage examples section for Tab component demonstrations.

Interactive Playground

Use the controls to customize the TabItem and see how it looks in real-time. Toggle between themes and hues to see how tab items adapt to different contexts. Note: This playground shows TabItem variants only. For Tab component variants, see the Usage Examples section.

Color
Show Start Icon
Show End Icon
Show Tab Label
Tab Item
<TabItem />
Anatomy

A TabItem consists of several parts that work together to create a cohesive interactive element.

Tab Item
Containerpadding, border-radius (for pill style)
Content Areaflex layout, gap
Label--body-*-text-size
Icon Spacing--spacing-200
Active Indicator2px bottom border (default style only)
Variants & States

TabItems come in different sizes, styles, and states to fit various use cases. The Tab component supports different configurations for organizing multiple TabItems.

Default Style

Standard tab style with bottom border indicator for active state. Use for most navigation scenarios.

Active
Tab #1
Pill Style

Rounded pill-style tabs with background highlight for active state. Use for more prominent tab navigation.

Active
Tab #1
Small Size

Compact tab size for space-constrained interfaces. Uses smaller text and icon sizes.

Small Tab
Side Style

Vertical sidebar tabs with full background highlight for active state. Use for side navigation.

Active
Tab #1
Medium Size

Standard tab size for most use cases. Provides comfortable touch targets and readability.

Medium Tab

For a complete matrix of all tab variants, sizes, and states, see the TabItem component in Figma and Tab component in Figma.

Usage Guidelines
Do
  • Use tabs to organize related content into distinct sections.
  • Keep tab labels concise and descriptive.
  • Use the default style for most navigation scenarios.
  • Limit the number of tabs to avoid overwhelming users (typically 3-5 tabs).
  • Ensure active tab state is clearly visible.
  • Use icons to enhance clarity when appropriate.
Don't
  • Don't use tabs for unrelated content sections.
  • Don't use too many tabs (more than 7-8) - consider alternative navigation patterns.
  • Don't use vague or ambiguous tab labels.
  • Don't disable tabs without explaining why.
  • Don't use tabs for hierarchical navigation (use menus instead).
  • Don't make tabs too small to tap comfortably on mobile.
Accessibility
  • Tabs must be keyboard accessible. Use proper ARIA attributes for tab navigation.
  • Provide descriptive labels for screen readers using aria-label when needed.
  • Ensure focus states are clearly visible with sufficient contrast.
  • Use disabled attribute for disabled tabs, not just visual styling.
  • Active tab state should be announced to screen readers.
API Reference

TabItem and Tab component props and types.

TabItemProps
interface TabItemProps { tabName?: string; state?: "default" | "active" | "hover" | "disabled"; size?: "sm" | "md"; style?: "default" | "pill" | "side"; placement?: "horizontal" | "vertical"; showStartIcon?: boolean; showEndIcon?: boolean; showTabLabel?: boolean; cornerRadius?: 0 | 1 | 2 | 3 | 4 | 5; startIcon?: React.ReactNode; endIcon?: React.ReactNode; onClick?: () => void; "aria-label"?: string; }
TabProps
interface TabProps { size?: "sm" | "md"; itemWidth?: "auto" | "equal"; style?: "default" | "pill" | "side"; placement?: "horizontal"; cornerRadius?: 0 | 1 | 2 | 3 | 4 | 5; children: React.ReactNode; "aria-label"?: string; }
TabItem Props
tabName
string
—
Text label for the tab item
state
"default" | "active" | "hover" | "disabled"
"default"
Visual state of the tab item
size
"sm" | "md"
"sm"
Tab item size
style
"default" | "pill" | "side"
"default"
Visual style variant
placement
"horizontal" | "vertical"
"horizontal"
Layout orientation
showStartIcon
boolean
true
Show icon at the start
showEndIcon
boolean
true
Show icon at the end (horizontal only)
showTabLabel
boolean
true
Show text label
cornerRadius
0 | 1 | 2 | 3 | 4 | 5
5
Corner radius step for pill style: 0=None, 1=100 (4px), 2=200 (8px), 3=300 (12px), 4=400 (16px), 5=Full (100%)
Tab Props
size
"sm" | "md"
"sm"
Tab size
itemWidth
"auto" | "equal"
"auto"
Width distribution for tab items. When set to "equal", each TabItem takes equal available width and the active indicator spans the full width of each item.
style
"default" | "pill" | "side"
"default"
Visual style variant. Use "side" for vertical sidebar tabs.
placement
"horizontal"
"horizontal"
Layout orientation
cornerRadius
0 | 1 | 2 | 3 | 4 | 5
5
Corner radius step for tab container (pill style): 0=None, 1=100 (4px), 2=200 (8px), 3=300 (12px), 4=400 (16px), 5=Full (100%)
Usage Examples

Copyable code snippets for common tab use cases.

Default Style
Active
Tab #1
Tab #2
<Tab> <TabItem>Active</TabItem> <TabItem>Tab #1</TabItem> <TabItem>Tab #2</TabItem> </Tab>
Pill Style
Active
Tab #1
Tab #2
<Tab style="pill" > <TabItem>Active</TabItem> <TabItem>Tab #1</TabItem> <TabItem>Tab #2</TabItem> </Tab>
Tab with Medium Size
Active
Tab #1
Tab #2
<Tab size="md" > <TabItem>Active</TabItem> <TabItem>Tab #1</TabItem> <TabItem>Tab #2</TabItem> </Tab>
Equal Width Items
Active
Tab #1
Tab #2
<Tab itemWidth="equal" > <TabItem>Active</TabItem> <TabItem>Tab #1</TabItem> <TabItem>Tab #2</TabItem> </Tab>
Vertical Placement
Active
Tab #1
Tab #2
import { Tab, TabItem } from 'beacon-ui'; import { PageFileIcon } from 'beacon-icons'; <Tab> <TabItem tabName="Active" state="active" placement="vertical" startIcon={<PageFileIcon size={16} />} /> <TabItem tabName="Tab #1" placement="vertical" startIcon={<PageFileIcon size={16} />} /> <TabItem tabName="Tab #2" placement="vertical" startIcon={<PageFileIcon size={16} />} /> </Tab>
Side Style
Active
Tab #1
Tab #2
<Tab style="side" > <TabItem>Active</TabItem> <TabItem>Tab #1</TabItem> <TabItem>Tab #2</TabItem> </Tab>