---
title: Tabs
description: Switch between peer panels with managed focus and activation.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Tabs

> Switch between peer panels with managed focus and activation.

## Anatomy

```text
Tabs [component; slot=root]
├── list [slot]
│   ├── indicator [slot]
│   └── trigger [slot]
│       ├── leading [slot]
│       └── label [slot]
└── content [slot]
```

String labels use the label slot; JSX labels render directly inside the trigger.

## Usage

Use Tabs to switch between peer panels while staying in the same page context. Use navigation links
when each destination needs its own URL and document state. Use [Stepper](https://moraine.subf.dev/components/stepper.md) for a
fixed sequence. Use [NavigationMenu](https://moraine.subf.dev/components/navigation-menu.md) for website destinations with
expandable panels.

```tsx
import { Tabs } from 'moraine'

export function Example() {
  return <Tabs items={[{ value: 'account', label: 'Account', content: 'Profile settings' }]} />
}
```

### Selected value

Use `value` with `onValueChange` for controlled tabs, or `defaultValue` for an initial local
selection. Without a matching enabled value, the first enabled tab is active. `onValueChange` fires
only when the user selects a different tab. Disabled items, and every tab while `disabled` is set,
cannot be selected; keyboard navigation skips disabled items.

Every item requires a unique `value`; an item that repeats an earlier value is disabled. An item can
also set `icon`, which renders before the label. Only the selected tab's panel is mounted. For JSX
panel content, pass a component as `content`: Tabs renders it with `{ value }` only while its tab is
selected, so an unselected panel is never built. This matters in SSR and MDX, where building a panel
eagerly can emit markup the hydrated tree does not expect.

```tsx
<Tabs
  value={tab()}
  onValueChange={setTab}
  items={[
    { value: 'overview', label: 'Overview', content: () => <OverviewPanel /> },
    {
      value: 'billing',
      label: 'Billing',
      content: (props) => <Billing value={props.value} />,
    },
  ]}
/>
```

### Activation and keyboard navigation

`activationMode="automatic"` (the default) selects a tab as arrow navigation moves focus. In manual
mode, arrows move focus and Enter or Space selects. `loop` (default `true`) wraps navigation at the
first and last enabled tabs. The arrow keys that move focus follow the list `orientation`.

```tsx
<Tabs items={TABS} activationMode="automatic" defaultValue="overview" />
<Tabs items={TABS} activationMode="manual" defaultValue="overview" />
```

| Key                                 | Description                                          |
| ----------------------------------- | ---------------------------------------------------- |
| <kbd>Arrow keys</kbd>               | Moves focus among enabled tabs by orientation.       |
| <kbd>Home</kbd> / <kbd>End</kbd>    | Moves focus to the first or last enabled tab.        |
| <kbd>Enter</kbd> / <kbd>Space</kbd> | Activates the focused tab in manual mode.            |
| <kbd>Tab</kbd>                      | Leaves the tab list according to normal focus order. |

## Examples

### Account settings owned by page state

Keep Account, Security, and Billing on one page. Store the selected tab in local state.

```tsx
import { Tabs } from 'moraine'
import type { TabsT } from 'moraine'
import { createSignal } from 'solid-js'

const TAB_ITEMS: TabsT.Item[] = [
  {
    value: 'account',
    label: 'Account',
    icon: 'i-lucide:user',
    content: (
      <div class="text-xs text-muted-foreground mt-2 p-3 b-1 b-border rounded-lg bg-card/40">
        Manage your account preferences, profile details, and email notifications.
      </div>
    ),
  },
  {
    value: 'security',
    label: 'Security',
    icon: 'i-lucide:shield',
    content: (
      <div class="text-xs text-muted-foreground mt-2 p-3 b-1 b-border rounded-lg bg-card/40">
        Configure two-factor authentication, active sessions, and API tokens.
      </div>
    ),
  },
  {
    value: 'billing',
    label: 'Billing',
    icon: 'i-lucide:credit-card',
    content: (
      <div class="text-xs text-muted-foreground mt-2 p-3 b-1 b-border rounded-lg bg-card/40">
        View past invoices, payment methods, and current subscription usage.
      </div>
    ),
  },
]

export function SelectionUsage() {
  const [tab, setTab] = createSignal('account')

  return (
    <div class="max-w-md w-full space-y-3">
      <Tabs items={TAB_ITEMS} value={tab()} onValueChange={setTab} />
      <p class="text-xs text-muted-foreground">
        Active tab: <span class="text-foreground font-medium font-mono">{tab()}</span>
      </p>
    </div>
  )
}
```

### Browse dashboard tabs as focus moves

`activationMode="automatic"` selects Overview, Analytics, or Logs while arrow keys move focus. Use
this for lightweight inspection panels.

```tsx
import { Tabs } from 'moraine'
import type { TabsT } from 'moraine'

const TABS: TabsT.Item[] = [
  {
    value: 'overview',
    label: 'Overview',
    content: (
      <div class="text-xs text-muted-foreground p-3">System status and resource metrics.</div>
    ),
  },
  {
    value: 'analytics',
    label: 'Analytics',
    content: (
      <div class="text-xs text-muted-foreground p-3">Traffic breakdowns and request volume.</div>
    ),
  },
  {
    value: 'logs',
    label: 'Logs',
    content: (
      <div class="text-xs text-muted-foreground p-3">Real-time application execution stream.</div>
    ),
  },
]

export function ActivationUsage() {
  return (
    <div class="max-w-md w-full">
      <Tabs items={TABS} activationMode="automatic" defaultValue="overview" />
    </div>
  )
}
```

### Confirm a settings tab with Enter

`activationMode="manual"` keeps the current panel until Enter or Space. Use it when switching tabs
should be an explicit commit, as in a settings wizard.

```tsx
import { Tabs } from 'moraine'
import type { TabsT } from 'moraine'

const SETTINGS_TABS: TabsT.Item[] = [
  {
    label: 'General',
    value: 'general',
    icon: 'i-lucide:sliders',
    content: (
      <div class="p-3 space-y-1">
        <h4 class="text-sm font-semibold">Workspace defaults</h4>
        <p class="text-xs text-muted-foreground">
          Name, timezone, and default branch. Arrow keys move focus; Enter or Space opens the panel.
        </p>
      </div>
    ),
  },
  {
    label: 'Deployments',
    value: 'deployments',
    icon: 'i-lucide:rocket',
    content: (
      <div class="p-3 space-y-1">
        <h4 class="text-sm font-semibold">Deployment gates</h4>
        <p class="text-xs text-muted-foreground">
          Require reviews before production. Manual activation keeps the previous panel visible
          until you confirm.
        </p>
      </div>
    ),
  },
  {
    label: 'Notifications',
    value: 'notifications',
    icon: 'i-lucide:bell',
    content: (
      <div class="p-3 space-y-1">
        <h4 class="text-sm font-semibold">Alert rules</h4>
        <p class="text-xs text-muted-foreground">Configure webhook dispatch channels.</p>
      </div>
    ),
  },
]

export function ActivationMode() {
  return (
    <div class="max-w-md w-full">
      <Tabs items={SETTINGS_TABS} activationMode="manual" defaultValue="general" />
    </div>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-disabled` | `tabs`, `tabs-trigger` | Present when the component, slot, or item is disabled. |
| `data-highlighted` | `tabs-trigger` | Present when the item is highlighted by pointer or keyboard navigation. |
| `data-selected` | `tabs-trigger`, `tabs-content` | Present when the item or tab is selected. |

### Props

Props for the Tabs component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| activationMode | 'automatic' \| 'manual' \| undefined | 'automatic' | Whether arrow-key focus movement activates the tab immediately (`automatic`) or only moves<br>focus until `Enter` or `Space` confirms it (`manual`). |
| defaultValue | string \| undefined | — | Initially active tab value for uncontrolled usage. The first enabled tab is active when omitted. |
| disabled | boolean \| undefined | false | Whether the whole tab list is disabled: no tab can be selected by click or keyboard. |
| id | string \| undefined | — | DOM `id` of the tabs root element; the trigger and panel ids derive from it. Generated when omitted. |
| items | ({<br>  /** Label to display on the tab trigger. It is also the tab's accessible name, so give icon-only<br>tabs a text label or an accessible alternative. */<br>  label?: JSX.Element;<br>  /** Icon to display before the label. */<br>  icon?: IconT.Name;<br>  /** Unique value identifying the tab in `value` and `onValueChange`. A tab that repeats an earlier<br>tab's value is disabled. */<br>  value: string;<br>  /** Content of the tab panel. Only the active tab's panel is mounted; switching tabs unmounts the<br>previous one. Accepts static JSX or a component receiving `{ value }`, which defers building the panel until it is shown. */<br>  content?: JSX.Element \| Component<ContentRenderProps>;<br>  /** Whether the tab is disabled: it cannot be selected and is skipped by arrow-key navigation. */<br>  disabled?: boolean;<br>})[] \| undefined | — | Array of tabs to display, in order. |
| loop | boolean \| undefined | true | Whether arrow-key navigation wraps from the last tab to the first and back. Disabled tabs are skipped. |
| onValueChange | ((value: string) => void) \| undefined | — | Called with the tab's `value` when the user selects a different tab by click or keyboard.<br>It does not fire for programmatic `value` changes, for the already-active tab, or while the<br>tabs are `disabled`. |
| orientation | 'horizontal' \| 'vertical' \| undefined | 'horizontal' | Direction in which tabs are laid out. It also decides which arrow keys move between tabs. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| value | string \| undefined | — | Controlled active tab value. When `undefined`, or when it matches no enabled tab, the first enabled tab is active. |
| variant | 'pill' \| 'link' \| undefined | 'pill' | Visual treatment of the component. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`items` example**

```tsx
import { Tabs } from 'moraine'

<Tabs
  defaultValue="code"
  items={[
    { value: 'code', label: 'Code', icon: 'icon-code' },
    { value: 'preview', label: 'Preview' },
    { value: 'history', label: 'History', disabled: true },
  ]}
/>
```
