Selection and preferences

useTabs

Manages a tabbed interface with controlled/uncontrolled value, arrow key navigation, roving tabindex, and automatic ARIA attributes for tab triggers and panels.

Copy React example Tabs component

Live component preview · Astro

Explore Tabs

Try the component this hook connects to. The preview uses the Astro adapter; the React example below uses useTabs.

All primitives are available as Astro components.

The same API surface is available in React.

Standards-based custom elements bring Lumen to framework-neutral pages.

React Native consumes the shared tokens and native component contracts.

SwiftUI provides native Apple-platform primitives.

Compose provides native Android and Wear OS primitives.

React usage

Import from @santi020k/lumen-react and spread the controller props onto the matching components.

import { Tabs, TabsList, TabsTrigger, TabsPanel } from '@santi020k/lumen-react'
import { useTabs } from '@santi020k/lumen-react'

export function SettingsTabs() {
  const tabs = useTabs({ defaultValue: 'general' })

  return (
    <Tabs {...tabs.rootProps}>
      <TabsList {...tabs.listProps}>
        <TabsTrigger {...tabs.getTriggerProps('general')}>General</TabsTrigger>
        <TabsTrigger {...tabs.getTriggerProps('security')}>Security</TabsTrigger>
      </TabsList>
      <TabsPanel {...tabs.getPanelProps('general')}>
        <p>General settings content.</p>
      </TabsPanel>
      <TabsPanel {...tabs.getPanelProps('security')}>
        <p>Security settings content.</p>
      </TabsPanel>
    </Tabs>
  )
}

import { Tabs, TabsList, TabsTrigger, TabsPanel } from '@santi020k/lumen-react'
import { useTabs } from '@santi020k/lumen-react'

export function SettingsTabs() {
  const tabs = useTabs({ defaultValue: 'general' })

  return (
    <Tabs {...tabs.rootProps}>
      <TabsList {...tabs.listProps}>
        <TabsTrigger {...tabs.getTriggerProps('general')}>General</TabsTrigger>
        <TabsTrigger {...tabs.getTriggerProps('security')}>Security</TabsTrigger>
      </TabsList>
      <TabsPanel {...tabs.getPanelProps('general')}>
        <p>General settings content.</p>
      </TabsPanel>
      <TabsPanel {...tabs.getPanelProps('security')}>
        <p>Security settings content.</p>
      </TabsPanel>
    </Tabs>
  )
}

Load @santi020k/lumen-react/styles.css once in your application. With React Server Components, put 'use client' at the top of the module that calls the hook. Follow the React setup guide for the framework boundary.

Options

Property	Type	Default	Description
defaultValue	string	""	Initial active tab value for uncontrolled usage.
value	string	-	Controlled active tab value.
onValueChange	(value: string) => void	-	Callback fired when the active tab changes.
orientation	"horizontal" \| "vertical"	"horizontal"	Tab navigation direction — affects which arrow keys are used.
id	string	auto	Base id for generated tab and panel ids.

Controller return values

Property	Type	Description
rootProps	LumenProps<"div">	Spread onto the tabs root wrapper.
listProps	LumenProps<"div">	Spread onto the tablist element.
getTriggerProps(value)	(value, props?) => LumenProps<"button">	Returns props for a tab trigger with the given value. Includes aria-selected, role, keyboard handlers.
getPanelProps(value)	(value, props?) => LumenProps<"div">	Returns props for a tab panel. Automatically hides non-active panels.
value	string	Currently active tab value.
setValue	Dispatch<SetStateAction<string>>	State setter for controlled usage.
rootRef	RefObject<HTMLElement>	Ref to the tabs root element.