Skip to main content

Tabs

A headless, accessible tabs component that provides complete keyboard navigation, orientation support, and ARIA compliance for tabbed interfaces.

Live Demo​

This demo starts with the Trend tab selected and highlights the active trigger with an underline treatment.

JavaScript
<div className='tabs-demo-container'>
<Tabs.Root defaultValue='trend' className='tabs'>
      <Tabs.List className='tabs-list'>
        <Tabs.Trigger value='recent' className='tab'>
          <span className='tab-label'>Recent</span>
        </Tabs.Trigger>
        <Tabs.Trigger value='popular' className='tab'>
          <span className='tab-label'>Popular</span>
        </Tabs.Trigger>
        <Tabs.Trigger value='trend' className='tab'>
          <span className='tab-label'>Trend</span>
        </Tabs.Trigger>
      </Tabs.List>
      <Tabs.Content value='trend'>
      </Tabs.Content>
</Tabs.Root>
</div>

Features​

  • ✅ Controlled and uncontrolled state management
  • ✅ Automatic first-tab selection in uncontrolled mode when no value / defaultValue is provided (without calling onValueChange)
  • ✅ Horizontal and vertical orientation configuration
  • ✅ Automatic and manual activation behavior
  • ✅ Lazy content rendering for performance
  • ✅ Force mount option for always-rendered content
  • ✅ Polymorphic rendering with as prop
  • ✅ Render props pattern for Tabs.Trigger customization
  • ✅ Disabled tab support

Import​

import { Tabs } from '@turkish-technology/spar';

Anatomy​

The Tabs component consists of compound parts that work together:

Parts
RootRoot container that manages state and provides context
ListContainer for tab triggers with keyboard navigation
TriggerClickable tab button that activates content
ContentContent panel associated with each tab
<Tabs.Root>
<Tabs.List>
<Tabs.Trigger />
<Tabs.Trigger />
</Tabs.List>
<Tabs.Content />
<Tabs.Content />
</Tabs.Root>

Data Flow​

  1. Tabs.Root manages selected value state and provides context to descendants
  2. Tabs.List handles roving focus and keyboard-driven tab traversal
  3. Tabs.Trigger registers itself in the tab registry and updates selection
  4. Tabs.Content renders the matching panel and reflects active/inactive state

Code Examples​

Controlled Tabs​

Use controlled tabs when the active panel needs to stay synced with routing, saved preferences, or external UI state.

function ControlledTabs() {
const [activeTab, setActiveTab] = useState('profile');

return (
<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
<Tabs.List>
<Tabs.Trigger value="profile">Profile</Tabs.Trigger>
<Tabs.Trigger value="settings">Settings</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="profile">Profile content here</Tabs.Content>
<Tabs.Content value="settings">Settings content here</Tabs.Content>
</Tabs.Root>
);
}

Vertical Orientation​

Vertical tabs work well for settings pages and other layouts where labels need more room.

function VerticalTabs() {
return (
<Tabs.Root orientation="vertical" defaultValue="tab1">
<Tabs.List>
<Tabs.Trigger value="tab1">First Tab</Tabs.Trigger>
<Tabs.Trigger value="tab2">Second Tab</Tabs.Trigger>
<Tabs.Trigger value="tab3">Third Tab</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="tab1">First content</Tabs.Content>
<Tabs.Content value="tab2">Second content</Tabs.Content>
<Tabs.Content value="tab3">Third content</Tabs.Content>
</Tabs.Root>
);
}

Manual Activation Mode​

Manual activation separates focus from selection so users can explore tab labels with the keyboard before committing.

function ManualActivationTabs() {
return (
<Tabs.Root activationMode="manual" defaultValue="home">
<Tabs.List>
<Tabs.Trigger value="home">Home</Tabs.Trigger>
<Tabs.Trigger value="about">About</Tabs.Trigger>
<Tabs.Trigger value="contact">Contact</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="home">Home page content</Tabs.Content>
<Tabs.Content value="about">About page content</Tabs.Content>
<Tabs.Content value="contact">Contact page content</Tabs.Content>
</Tabs.Root>
);
}

Render Props Pattern​

Render props let you build richer trigger content while still reading tab selection and focus state from the component.

function RenderPropsTabs() {
return (
<Tabs.Root defaultValue="dashboard">
<Tabs.List>
<Tabs.Trigger value="dashboard">
{({ isSelected, isFocused }) => (
<span className={isSelected ? 'selected' : ''}>
<DashboardIcon />
Dashboard
{isFocused && <span className="focus-indicator" />}
</span>
)}
</Tabs.Trigger>
<Tabs.Trigger value="analytics">
{({ isSelected }) => (
<span className={isSelected ? 'selected' : ''}>Analytics</span>
)}
</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="dashboard">Dashboard content</Tabs.Content>
<Tabs.Content value="analytics">Analytics content</Tabs.Content>
</Tabs.Root>
);
}

Force Mount Content​

Use forceMount for panels that should stay in the DOM, such as forms, media players, or stateful widgets.

function ForceMountTabs() {
return (
<Tabs.Root defaultValue="lazy">
<Tabs.List>
<Tabs.Trigger value="lazy">Lazy Content</Tabs.Trigger>
<Tabs.Trigger value="eager">Always Mounted</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="lazy">
This content is only rendered when active
</Tabs.Content>
<Tabs.Content value="eager" forceMount>
This content is always in the DOM (useful for forms, videos, etc.)
</Tabs.Content>
</Tabs.Root>
);
}

API Reference​

Tabs / Tabs.Root​

The root state container for the tabs system. Tabs and Tabs.Root are the same component - the difference is only import/notation style.

Props​

NameTypeDefaultDescription
id?stringundefinedBase id used to derive trigger/panel ids ({id}-trigger-{value} etc.)
value?stringundefinedControlled selected tab value
defaultValue?stringundefinedInitial selected tab value for uncontrolled usage
onValueChange?(value: string) => voidundefinedCalled when the user changes the selected tab; never on mount
orientation?'horizontal' | 'vertical''horizontal'Orientation used by list/panels and keyboard rules
dir?'ltr' | 'rtl''ltr'Direction used by horizontal arrow navigation
activationMode?'automatic' | 'manual''automatic'automatic: focus activates, manual: Enter/Space activates
as?React.ElementType'div'Element type to render
...propsComponentPropsWithRef<'div'> + as element props—Forwards supported HTML attributes/events to the rendered root element

Events​

NameParametersDescriptionWhen Triggered
onValueChange?value: stringReports next selected valueThe value changes via click, keyboard activation, or select(); not fired on mount or when re-activating the selected tab

HTML Attributes​

AttributeValuePurpose
data-orientationhorizontal | verticalExposes configured orientation
data-dirltr | rtlExposes configured text direction

Tabs.List​

Props​

NameTypeDefaultDescription
as?React.ElementType'div'Element type to render
...propsComponentPropsWithRef<'div'> + as element props—Forwards supported HTML attributes/events to the list

Events​

NameParametersDescriptionWhen Triggered
onKeyDown?event: React.KeyboardEvent<HTMLDivElement>Custom key handler (composed)Called after built-in keyboard navigation logic

HTML Attributes​

AttributeValuePurpose
roletablistIdentifies the element as a tab list
aria-orientationhorizontal | verticalIndicates tab list orientation
data-orientationhorizontal | verticalIndicates tab list orientation

Tabs.Trigger​

Extends all Button component props including polymorphic rendering via the as prop.

Props​

NameTypeDefaultDescription
valuestring—Unique identifier for this tab
children?React.ReactNode | ((state: TabsTriggerRenderProps) => React.ReactNode)undefinedTrigger content or render-prop function
as?React.ElementType'button'Element type to render
disabled?booleanfalseDisables trigger selection and interaction
autoFocus?booleanfalseFocuses trigger on mount
isLoading?booleanfalseInherited from Button; exposes loading semantics
isPressed?booleanundefinedInherited from Button; enables toggle-button behavior
onPressedChange?(pressed: boolean) => voidundefinedInherited callback for toggle state changes
...propsButton HTML/button props + as element props—Forwards supported attributes/events to the trigger

TabsTriggerRenderProps​

PropertyTypeDescription
isSelectedbooleanWhether this tab is currently selected
select() => voidFunction to select this tab programmatically
disabledbooleanWhether this tab is disabled
isFocusedbooleanWhether this tab is currently focused
orientationOrientationThe tab's orientation

Events​

NameParametersDescriptionWhen Triggered
onClick?event: React.MouseEvent<HTMLButtonElement>Tab clickedUser clicks the tab trigger
onFocus?event: React.FocusEvent<HTMLButtonElement>Tab focusedTab receives focus via keyboard or mouse
onBlur?event: React.FocusEvent<HTMLButtonElement>Tab blurredTab loses focus

HTML Attributes​

AttributeValuePurpose
id\${baseId}-trigger-\${value}Stable trigger id used by panel relationship
roletabIdentifies the element as a tab
aria-selectedtrue | falseIndicates whether this tab is selected
aria-controls\${baseId}-panel-\${value}References controlled tab panel
tabIndex0 | -1Implements roving tabindex behavior
disabledbooleanNative disabled attribute when rendered as button
aria-disabledtrue (conditional)Added by Button when disabled and rendered as non-button
data-stateactive | inactiveExposes selected state
data-orientationhorizontal | verticalExposes current orientation
data-valuestringStores trigger value for keyboard navigation
data-disabled'' | undefinedInherited from Button when disabled
data-loading'' | undefinedInherited from Button when isLoading is true
data-pressed'' | undefinedInherited from Button when toggle mode is active and pressed
data-autofocus'' | undefinedInherited from Button when autoFocus is true

Tabs.Content​

Props​

NameTypeDefaultDescription
valuestring—Unique identifier matching a Tabs.Trigger
forceMount?booleanfalseKeeps panel mounted even when inactive
as?React.ElementType'div'Element type to render
...propsComponentPropsWithRef<'div'> + as element props—Forwards supported HTML attributes/events

Events​

No component-specific events are defined. Standard forwarded DOM events can be passed via ...props.

HTML Attributes​

AttributeValuePurpose
id\${baseId}-panel-\${value}Stable panel id for trigger relationship
roletabpanelIdentifies the element as a tab panel
aria-labelledby\${baseId}-trigger-\${value}References controlling trigger
tabIndex0Makes rendered panel programmatically focusable
hiddentrue | falseMarks mounted but inactive panel as hidden
data-stateactive | inactiveExposes panel active state
data-orientationhorizontal | verticalExposes current orientation

Keyboard Interactions​

KeyActionContextNotes
TabMoves focus in document tab orderGlobalBrowser-native behavior; not intercepted by Tabs
ArrowRightFocuses next enabled tabHorizontal listUses dir; wraps when end is reached; skips disabled tabs
ArrowLeftFocuses previous enabled tabHorizontal listUses dir; wraps when start is reached; skips disabled tabs
ArrowDownFocuses next enabled tabVertical listWraps when end is reached; skips disabled tabs
ArrowUpFocuses previous enabled tabVertical listWraps when start is reached; skips disabled tabs
HomeFocuses first enabled tabList focusedSelects it in automatic mode
EndFocuses last enabled tabList focusedSelects it in automatic mode
Enter or SpaceActivates focused triggerTrigger focusedCommits the focused tab in manual mode; ignored on disabled triggers

Note: In automatic mode, arrow/home/end navigation both focuses and selects. In manual mode, those keys only move focus; use Enter or Space to commit selection after moving focus.