Tab Bar

Props

• label: string (required) -- accessible label for the tab list, applied via aria-label
• children: slot (required) -- tab button elements to render inside the tablist
• ...restProps: unknown -- additional attributes spread onto the <div> element

Keyboard Interactions

• Arrow Right: Moves focus to the next tab; wraps from the last tab to the first
• Arrow Left: Moves focus to the previous tab; wraps from the first tab to the last
• Home: Moves focus to the first tab
• End: Moves focus to the last tab
• Tab: Moves focus into and out of the tab list (only one tab in the list is in the tab order at a time)

ARIA

• role="tablist" -- identifies the container as a list of tabs
• aria-label={label} -- provides an accessible name for the tab list so screen readers announce its purpose
• Child tabs should have role="tab" and aria-selected attributes (managed by consumer)
• Associated tab panels should have role="tabpanel" with aria-labelledby pointing to the corresponding tab (managed by consumer)

When to Use

• Use to let users navigate between related sections of content without leaving the page
• Use when content naturally divides into distinct categories that users will access one at a time
• Use to reduce page length by showing only the relevant section
• Use when there are 2-6 sections -- enough to justify tabs, few enough to remain scannable

When Not to Use

• Do not use when users need to compare information across sections -- show all content on one page or use a Table
• Do not use with only one section -- show the content directly without tabs
• Do not use for sequential steps or progress -- use TaskList or a multi-page form with BackLink
• Do not use for navigation between different pages -- use NavigationMenu or BreadcrumbNav instead

Headless

This headless component renders a <div> with role="tablist", aria-label, and built-in arrow key navigation (Left/Right to cycle tabs, Home/End to jump to first/last). The consumer provides tab button children, manages selection state, associates tab panels, and applies all visual styling.

Styles

The consumer provides all CSS styling. The component renders with a .tab-bar class for targeting. No default styles are included — this is a fully headless component.

Testing

• Verify the component renders a <div> element with class tab-bar
• Verify role="tablist"` -- identifies the container as a list of tabs
• Verify aria-label={label}` -- provides an accessible name for the tab list so screen readers announce its purpose
• Verify Child tabs should have role="tab" and aria-selected attributes (managed by consumer)
• Verify Associated tab panels should have role="tabpanel" with aria-labelledby pointing to the corresponding tab (managed by consumer)
• Verify keyboard interactions work correctly
• Verify pass-through attributes are applied

Advice

• Designers: Clearly indicate the active tab with a visual treatment such as an underline, background color, or border. Keep tab labels short and descriptive.
• Developers: Pair each TabBarButton with a corresponding role="tabpanel" element linked via aria-controls and aria-labelledby. Manage the aria-selected state on child tab buttons from the consumer.

Implementation Notes

• Renders a <div> element with role="tablist" for ARIA semantics
• Uses two-way this binding to capture a reference to the tablist element for DOM queries
• Queries all child elements with [role='tab'] to build the list of navigable tabs
• Implements keyboard navigation via an onkeydown handler:
  • ArrowRight moves focus to the next tab (wraps to first)
  • ArrowLeft moves focus to the previous tab (wraps to last)
  • Home moves focus to the first tab
  • End moves focus to the last tab
• Uses reactive state for the internal DOM reference (tablistRef)
• Consumer is responsible for managing aria-selected state on tab buttons and displaying corresponding tab panels
• Spreads restProps onto the div for consumer customization

Composition

TabBar uses the Bar/BarButton composition pattern. Place TabBarButton components as children inside TabBar. The TabBar provides the role="tablist" container with keyboard navigation, while each TabBarButton provides role="tab" with selection state and panel association.

Related components

• tab-bar-button — one tab button in a tab group

References

• WAI-ARIA Tabs Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
• WAI-ARIA Authoring Practices - Tabs Example: https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-automatic/