Inputs

SegmentedTabs

Tabs and toggles with one indicator that glides between options.

A segmented toggle or tab strip whose single shared indicator glides between options. Two variants (boxed segmented, or a soft pill over an underline), icons, sizes, full width, controlled or uncontrolled. Full WAI-ARIA tabs keyboard support, weight-stable labels, scrolls sideways and keeps the selection in view on narrow screens.

Installation

Add the package. SegmentedTabs is a segmented toggle or tab strip with one shared indicator that slides between options. It ships its own CSS.

pnpm add @roy-ui/ui

Import

import { SegmentedTabs } from '@roy-ui/ui';

// or just this component:
import { SegmentedTabs } from '@roy-ui/ui/segmented-tabs';

Usage

Pass an items array. Without value it is uncontrolled and starts on defaultValue, or on the first enabled item. Give it an aria-label so screen readers can name the tab list.

Segmented

The default boxed toggle, in md and sm. Disabled items are skipped by the keyboard.

tsx

<SegmentedTabs
  aria-label="Billing period"
  items={[
    { value: 'monthly', label: 'Monthly' },
    { value: 'yearly', label: 'Yearly' },
    { value: 'lifetime', label: 'Lifetime', disabled: true },
  ]}
/>

<SegmentedTabs size="sm" defaultValue="list" aria-label="View" items={views} />

Variants

variant='underline' gives a tab strip: a soft pill sits over an underline. Each item can take a leading icon, which is sized to 16px.

Underline with icons

Icons sit before the label; the pill and underline glide together.

tsx

<SegmentedTabs
  variant="underline"
  aria-label="Sections"
  items={[
    { value: 'overview', label: 'Overview', icon: <HomeIcon /> },
    { value: 'analytics', label: 'Analytics', icon: <ChartIcon /> },
    { value: 'settings', label: 'Settings', icon: <GearIcon /> },
  ]}
/>

Controlled, with panels

Pass value and onValueChange to control it. With panelIdPrefix, each tab gets aria-controls='{prefix}-{value}'. Give your panels those ids and role='tabpanel'. The value type is inferred from items, so onValueChange receives your union type.

The source for this component lives in one .tsx file and one .css file.

tsx

const [tab, setTab] = useState<'code' | 'preview' | 'notes'>('code');

<SegmentedTabs
  aria-label="Content"
  items={items}
  value={tab}
  onValueChange={setTab}
  panelIdPrefix="content"
/>
{items.map((i) => (
  <div key={i.value} id={`content-${i.value}`} role="tabpanel" hidden={i.value !== tab}>
    …
  </div>
))}

Full width

fullWidth makes the items stretch to fill the container equally.

tsx

<SegmentedTabs fullWidth defaultValue="system" aria-label="Theme" items={themes} />

Behavior & accessibility

It follows the WAI-ARIA tabs pattern: role='tablist' and role='tab', roving tabindex, and ←/→ to move and select (Home and End jump to the ends), skipping disabled items. The indicator glides with translate and width over 250ms. It snaps into place on first paint, on resize, and when items, variant or size change. Under prefers-reduced-motion it moves without animating. Labels reserve room for their heavier selected weight, so selecting a tab never shifts the layout. When the strip overflows, it scrolls sideways and keeps the selected tab in view. theme='auto' follows prefers-color-scheme.

Theming

/* Override on the component or on :root. */
.royui-segtabs {
  --royui-segtabs-track: rgba(140, 146, 158, 0.12);
  --royui-segtabs-pill: #ffffff;
  --royui-segtabs-pill-shadow: 0 1px 2px rgba(0, 0, 0, 0.12);
  --royui-segtabs-fg: #111827;
  --royui-segtabs-muted: #6b7280;
  --royui-segtabs-underline: rgba(140, 146, 158, 0.3);
  --royui-segtabs-ring: #60a5fa;
  --royui-segtabs-duration: 250ms;
}

Props

Other props you pass (aria-label, className, style, data-*, event handlers) are spread onto the tablist div. The ref also points to that div.

Prop	Type	Default	Description
`items`	`SegmentedTabsItem<V>[]`	`—`	Options: { value, label, icon?, disabled? }. Required.
`value`	`V`	`—`	Controlled selected value.
`defaultValue`	`V`	`first enabled item`	Initial value when uncontrolled.
`onValueChange`	`(value: V) => void`	`—`	Called with the newly selected value.
`variant`	`'segmented' \| 'underline'`	`'segmented'`	Boxed toggle, or a tab strip with a pill over an underline.
`size`	`'sm' \| 'md'`	`'md'`	Control height and font size.
`fullWidth`	`boolean`	`false`	Stretch items to fill the container.
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Colour scheme. auto follows prefers-color-scheme.
`panelIdPrefix`	`string`	`—`	When set, each tab gets aria-controls="{prefix}-{value}".
`className`	`string`	`—`	Extra classes for the tablist.

SegmentedTabs

Tabs and toggles with one indicator that glides between options.

<SegmentedTabs aria-label="Billing period" items={[ { value: 'monthly', label: 'Monthly' }, { value: 'yearly', label: 'Yearly' }, { value: 'lifetime', label: 'Lifetime', disabled: true }, ]} /> <SegmentedTabs size="sm" defaultValue="list" aria-label="View" items={views} />

<SegmentedTabs variant="underline" aria-label="Sections" items={[ { value: 'overview', label: 'Overview', icon: <HomeIcon /> }, { value: 'analytics', label: 'Analytics', icon: <ChartIcon /> }, { value: 'settings', label: 'Settings', icon: <GearIcon /> }, ]} />

const [tab, setTab] = useState<'code' | 'preview' | 'notes'>('code'); <SegmentedTabs aria-label="Content" items={items} value={tab} onValueChange={setTab} panelIdPrefix="content" /> {items.map((i) => ( <div key={i.value} id={`content-${i.value}`} role="tabpanel" hidden={i.value !== tab}> … </div> ))}

Behavior & accessibility

/* Override on the component or on :root. */ .royui-segtabs { --royui-segtabs-track: rgba(140, 146, 158, 0.12); --royui-segtabs-pill: #ffffff; --royui-segtabs-pill-shadow: 0 1px 2px rgba(0, 0, 0, 0.12); --royui-segtabs-fg: #111827; --royui-segtabs-muted: #6b7280; --royui-segtabs-underline: rgba(140, 146, 158, 0.3); --royui-segtabs-ring: #60a5fa; --royui-segtabs-duration: 250ms; }

Prop

Type

Default

Description

items

SegmentedTabsItem<V>[]

—

Options: { value, label, icon?, disabled? }. Required.

value

V

—

Controlled selected value.

defaultValue

V

first enabled item

Initial value when uncontrolled.

onValueChange

(value: V) => void

—

Called with the newly selected value.

variant

'segmented' | 'underline'

'segmented'

Boxed toggle, or a tab strip with a pill over an underline.

size

'sm' | 'md'

'md'

Control height and font size.

fullWidth

boolean

false

Stretch items to fill the container.

theme

'light' | 'dark' | 'auto'

'auto'

Colour scheme. auto follows prefers-color-scheme.

panelIdPrefix

string

—

When set, each tab gets aria-controls="{prefix}-{value}".

className

string

—

Extra classes for the tablist.