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.
Code < 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:
Root Root container that manages state and provides context
List Container for tab triggers with keyboard navigation
Trigger Clickable tab button that activates content
Content Content panel associated with each tab
< Tabs.Root >
< Tabs.List >
< Tabs.Trigger />
< Tabs.Trigger />
</ Tabs.List >
< Tabs.Content />
< Tabs.Content />
</ Tabs.Root >
Data Flow
Tabs.Root manages selected value state and provides context to
descendants
Tabs.List handles roving focus and keyboard-driven tab traversal
Tabs.Trigger registers itself in the tab registry and updates selection
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
Name Type Default Description 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 activatesas?React.ElementType'div'Element type to render ...propsComponentPropsWithRef<'div'> + as element props— Forwards supported HTML attributes/events to the rendered root element
Events
Name Parameters Description When Triggered onValueChange?value: stringReports next selected value The value changes via click, keyboard activation, or select(); not fired on mount or when re-activating the selected tab
HTML Attributes
Attribute Value Purpose data-orientationhorizontal | verticalExposes configured orientation data-dirltr | rtlExposes configured text direction
Tabs.List
Props
Name Type Default Description as?React.ElementType'div'Element type to render ...propsComponentPropsWithRef<'div'> + as element props— Forwards supported HTML attributes/events to the list
Events
Name Parameters Description When Triggered onKeyDown?event: React.KeyboardEvent<HTMLDivElement>Custom key handler (composed) Called after built-in keyboard navigation logic
HTML Attributes
Attribute Value Purpose 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
Name Type Default Description 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
Property Type Description 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
Name Parameters Description When Triggered onClick?event: React.MouseEvent<HTMLButtonElement>Tab clicked User clicks the tab trigger onFocus?event: React.FocusEvent<HTMLButtonElement>Tab focused Tab receives focus via keyboard or mouse onBlur?event: React.FocusEvent<HTMLButtonElement>Tab blurred Tab loses focus
HTML Attributes
Attribute Value Purpose 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
Name Type Default Description 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
Attribute Value Purpose 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
Key Action Context Notes TabMoves focus in document tab order Global Browser-native behavior; not intercepted by Tabs ArrowRightFocuses next enabled tab Horizontal list Uses dir; wraps when end is reached; skips disabled tabs ArrowLeftFocuses previous enabled tab Horizontal list Uses dir; wraps when start is reached; skips disabled tabs ArrowDownFocuses next enabled tab Vertical list Wraps when end is reached; skips disabled tabs ArrowUpFocuses previous enabled tab Vertical list Wraps when start is reached; skips disabled tabs HomeFocuses first enabled tab List focused Selects it in automatic mode EndFocuses last enabled tab List focused Selects it in automatic mode Enter or SpaceActivates focused trigger Trigger focused Commits 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.