# Tabs

Switches between related views.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Tabs.tsx)

Figma: [Controls/Tab](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3285) (`Tabs.Tab`), [Tab](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3208) (`Tabs.Tab`)

## Overview

Tabs render an underlined or pill tab list over a set of panels. Use them for related content, and use links for page navigation.

## Examples

### Basic

```tsx
import { Tabs } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Tabs.Root defaultValue="overview">
      <Tabs.List aria-label="Sections">
        <Tabs.Tab value="overview">Overview</Tabs.Tab>
        <Tabs.Tab value="activity">Activity</Tabs.Tab>
        <Tabs.Tab value="settings">Settings</Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
      <Tabs.Panel value="overview">Overview content</Tabs.Panel>
      <Tabs.Panel value="activity">Activity content</Tabs.Panel>
      <Tabs.Panel value="settings">Settings content</Tabs.Panel>
    </Tabs.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Basic.tsx)

### Size

Set `size` on `Tabs.List` to `small`, `medium` (default), or `large`, for 32px, 40px, or 56px tabs.

```tsx
import { Stack, Tabs } from '@tempoxyz/ds'
import { Plus } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <Stack align="start" gap="24">
      {(['small', 'medium', 'large'] as const).map((size) => (
        <Tabs.Root defaultValue="overview" key={size}>
          <Tabs.List aria-label={`Sections ${size}`} size={size}>
            <Tabs.Tab value="overview">Overview</Tabs.Tab>
            <Tabs.Tab value="activity">
              <Plus />
              Activity
            </Tabs.Tab>
            <Tabs.Tab disabled value="settings">
              Settings
            </Tabs.Tab>
            <Tabs.Indicator />
          </Tabs.List>
          <Tabs.Panel value="overview">Overview content</Tabs.Panel>
          <Tabs.Panel value="activity">Activity content</Tabs.Panel>
        </Tabs.Root>
      ))}
    </Stack>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Size.tsx)

### Disabled

Set `disabled` on a `Tabs.Tab` to skip it during selection.

```tsx
import { Tabs } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Tabs.Root defaultValue="overview">
      <Tabs.List aria-label="Sections">
        <Tabs.Tab value="overview">Overview</Tabs.Tab>
        <Tabs.Tab value="activity">Activity</Tabs.Tab>
        <Tabs.Tab disabled value="settings">
          Settings
        </Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
      <Tabs.Panel value="overview">Overview content</Tabs.Panel>
      <Tabs.Panel value="activity">Activity content</Tabs.Panel>
    </Tabs.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Disabled.tsx)

### Expand

Set `expand` on `Tabs.List` to stretch the tabs across the available width.

```tsx
import { Tabs } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Tabs.Root defaultValue="activity" style={{ width: '20rem' }}>
      <Tabs.List aria-label="Account" expand>
        <Tabs.Tab value="activity">Activity</Tabs.Tab>
        <Tabs.Tab value="assets">Assets</Tabs.Tab>
        <Tabs.Tab value="keys">Keys</Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
    </Tabs.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Expand.tsx)

### Pill

Set `variant="pill"` on `Tabs.List` for filled tabs. The fill marks the active tab, so a pill list takes no `Tabs.Indicator`. Pill tabs are 32px, 40px, or 48px tall.

```tsx
import { Stack, Tabs } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Stack align="start" gap="24">
      {(['small', 'medium', 'large'] as const).map((size) => (
        <Tabs.Root defaultValue="all" key={size}>
          <Tabs.List aria-label={`Transfers ${size}`} size={size} variant="pill">
            <Tabs.Tab value="all">All</Tabs.Tab>
            <Tabs.Tab value="payments">Payments</Tabs.Tab>
            <Tabs.Tab value="payouts">Payouts</Tabs.Tab>
          </Tabs.List>
        </Tabs.Root>
      ))}
    </Stack>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Pill.tsx)

### Appearance

Set `appearance` on a pill `Tabs.List` to `base` (default) on the page, `inverse` on an inverse surface, or `overlay` over an image or video.

```tsx
import { Stack, Tabs, variants } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Stack gap="16">
      {(['base', 'inverse', 'overlay'] as const).map((appearance) => (
        <div key={appearance} {...styles.surface({ appearance })}>
          <Tabs.Root defaultValue="all">
            <Tabs.List
              appearance={appearance}
              aria-label={`Transfers ${appearance}`}
              variant="pill"
            >
              <Tabs.Tab value="all">All</Tabs.Tab>
              <Tabs.Tab value="payments">Payments</Tabs.Tab>
              <Tabs.Tab value="payouts">Payouts</Tabs.Tab>
            </Tabs.List>
          </Tabs.Root>
        </div>
      ))}
    </Stack>
  )
}

namespace styles {
  export const surface = variants({
    base: { borderRadius: 'sm', padding: '16' },
    variants: {
      appearance: {
        base: { backgroundColor: 'background.primary' },
        inverse: { backgroundColor: 'inverse.background.primary' },
        overlay: {
          backgroundImage: 'linear-gradient(135deg, #4471ed, #7e59e4) !custom',
        },
      },
    },
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Tabs/Appearance.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Tabs } from '@tempoxyz/ds'

<Tabs.Root>
  <Tabs.List>
    <Tabs.Tab />
    <Tabs.Indicator />
  </Tabs.List>
  <Tabs.Panel />
</Tabs.Root>
```

## Guidelines

### When to Use

* Switch between views of one subject at the same level, such as a webhook's Overview, Deliveries, and Settings.
* Split a dense page into parts used one at a time, such as Balances and Activity on a wallet's home screen.

### When Not to Use

* Use [ChoiceGroup](/docs/components/choice-group) to pick a value that changes the current view, such as a chart's 1D, 1W, or 1M range.
* Use [SidebarMenu](/docs/components/sidebar-menu) or links to move between pages with their own URLs.
* Use [Stepper](/docs/components/stepper) for steps completed in order.
* Use [Accordion](/docs/components/accordion) to open several sections at once, or to compare them.

### Keep Tabs Few and Short

Use two to five tabs with one-word or two-word labels. Overflowing tabs scroll sideways, and tabs past the edge are easy to miss.

* **Never applies:** Hide the tab.
* **Temporarily unavailable:** Disable the tab, such as Deliveries before a webhook's first event, and state why in the open panel.

**Do:** Use a few short, parallel labels.

```tsx
/** Do example for "Keep Tabs Few and Short" on the Tabs page: use a few short, parallel labels. @module */
import { Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Tabs.Root defaultValue="overview">
      <Tabs.List aria-label="Webhook">
        <Tabs.Tab value="overview">Overview</Tabs.Tab>
        <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
        <Tabs.Tab value="settings">Settings</Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
    </Tabs.Root>
  )
}
```

**Don't:** Add so many tabs that the row scrolls.

```tsx
/**
 * Don't example for "Keep Tabs Few and Short" on the Tabs page.
 * Don't add so many tabs that the row scrolls.
 * @module
 */
import { style, Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Tabs.Root defaultValue="overview" {...styles.root()}>
      <Tabs.List aria-label="Webhook">
        <Tabs.Tab value="overview">Endpoint overview</Tabs.Tab>
        <Tabs.Tab value="deliveries">Recent deliveries</Tabs.Tab>
        <Tabs.Tab value="failed">Failed attempts</Tabs.Tab>
        <Tabs.Tab value="secrets">Signing secrets</Tabs.Tab>
        <Tabs.Tab value="settings">Settings</Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
    </Tabs.Root>
  )
}

namespace styles {
  export const root = style({ maxWidth: '100% !custom' })
}
```

### Place One Indicator in Every Underline List

Put a `Tabs.Indicator` after the tabs in each underline `Tabs.List`. It slides a bar under the active tab.

**Do:** End every list with a `Tabs.Indicator`.

```tsx
/** Do example for "Keep Tabs Few and Short" on the Tabs page: use a few short, parallel labels. @module */
import { Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Tabs.Root defaultValue="overview">
      <Tabs.List aria-label="Webhook">
        <Tabs.Tab value="overview">Overview</Tabs.Tab>
        <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
        <Tabs.Tab value="settings">Settings</Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
    </Tabs.Root>
  )
}
```

**Don't:** Leave out the indicator, so only the label marks the active tab.

```tsx
/**
 * Don't example for "Place One Indicator in Every List" on the Tabs page.
 * Don't leave out the indicator, so only the label marks the active tab.
 * @module
 */
import { Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Tabs.Root defaultValue="overview">
      <Tabs.List aria-label="Webhook">
        <Tabs.Tab value="overview">Overview</Tabs.Tab>
        <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
        <Tabs.Tab value="settings">Settings</Tabs.Tab>
      </Tabs.List>
    </Tabs.Root>
  )
}
```

### Keep Panels Independent

Make each panel complete on its own. A Save button in one panel can't show errors in another, so use a [Stepper](/docs/components/stepper) flow or one longer form.

**Do:** Keep the fields of one form together.

```tsx
/** Do example for "Keep Panels Independent" on the Tabs page: keep the fields of one form together. @module */
import { Button, Field, Stack, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Stack gap="16" {...styles.fill()}>
      <Field.Root>
        <Field.Label>Key name</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="Checkout server" />
        </TextInput.Group>
      </Field.Root>
      <Field.Root>
        <Field.Label>Daily limit</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="5,000.00 USDC" />
        </TextInput.Group>
      </Field.Root>
      <div {...styles.actions()}>
        <Button size="small">Save key</Button>
      </div>
    </Stack>
  )
}

namespace styles {
  export const actions = style({ columnGap: '8', display: 'flex', justifyContent: 'flex-end' })

  export const fill = style({ width: '100% !custom' })
}
```

**Don't:** Split a form across tabs.

```tsx
/** Don't example for "Keep Panels Independent" on the Tabs page. Don't split a form across tabs. @module */
import { Button, Field, Stack, style, Tabs, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Tabs.Root defaultValue="details" {...styles.fill()}>
      <Tabs.List aria-label="Key" size="small">
        <Tabs.Tab value="details">Details</Tabs.Tab>
        <Tabs.Tab value="limits">Limits</Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
      <Tabs.Panel value="details">
        <Stack gap="16" {...styles.panel()}>
          <Field.Root>
            <Field.Label>Key name</Field.Label>
            <TextInput.Group>
              <TextInput.Control defaultValue="Checkout server" />
            </TextInput.Group>
          </Field.Root>
          <div {...styles.actions()}>
            <Button size="small">Save key</Button>
          </div>
        </Stack>
      </Tabs.Panel>
    </Tabs.Root>
  )
}

namespace styles {
  export const actions = style({ columnGap: '8', display: 'flex', justifyContent: 'flex-end' })

  export const fill = style({ width: '100% !custom' })

  export const panel = style({ marginBlockStart: '16' })
}
```

### Keep the Selected Tab on Reload

If a tab marks a significant view, store it in the URL. Control `Tabs.Root` with `value` and `onValueChange`.

**Do:** Store the tab in the URL, such as `?tab=deliveries`, so a reload or a shared link opens it.

```tsx
/**
 * Do example for "Keep the Selected Tab on Reload" on the Tabs page.
 * Store the tab in the URL, such as `?tab=deliveries`, so a reload or a shared link opens it.
 * @module
 */
import { style, Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <span {...styles.address()}>console.tempo.xyz/webhooks/wh_8f3a?tab=deliveries</span>
      <Tabs.Root defaultValue="deliveries">
        <Tabs.List aria-label="Webhook" size="small">
          <Tabs.Tab value="overview">Overview</Tabs.Tab>
          <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
          <Tabs.Tab value="settings">Settings</Tabs.Tab>
          <Tabs.Indicator />
        </Tabs.List>
      </Tabs.Root>
    </div>
  )
}

namespace styles {
  export const address = style({
    backgroundColor: 'container.regular',
    borderRadius: 'full',
    color: 'content.secondary',
    cornerShape: 'round',
    paddingBlock: '4',
    paddingInline: '12',
    typography: 'body.b3',
  })

  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '16' })
}
```

**Don't:** Reset a reloaded or shared page to the first tab.

```tsx
/**
 * Don't example for "Keep the Selected Tab on Reload" on the Tabs page.
 * Don't reset a reloaded or shared page to the first tab.
 * @module
 */
import { style, Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <span {...styles.address()}>console.tempo.xyz/webhooks/wh_8f3a</span>
      <Tabs.Root defaultValue="overview">
        <Tabs.List aria-label="Webhook" size="small">
          <Tabs.Tab value="overview">Overview</Tabs.Tab>
          <Tabs.Tab value="deliveries">Deliveries</Tabs.Tab>
          <Tabs.Tab value="settings">Settings</Tabs.Tab>
          <Tabs.Indicator />
        </Tabs.List>
      </Tabs.Root>
    </div>
  )
}

namespace styles {
  export const address = style({
    backgroundColor: 'container.regular',
    borderRadius: 'full',
    color: 'content.secondary',
    cornerShape: 'round',
    paddingBlock: '4',
    paddingInline: '12',
    typography: 'body.b3',
  })

  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '16' })
}
```

### Expand Tabs in Narrow Containers

Set `expand` in a narrow container, such as a [Surface](/docs/components/surface) or a phone-width column. Leave it off across a wide page, where stretched tabs drift apart.

**Do:** Stretch the tabs across a narrow card with `expand`.

```tsx
/**
 * Do example for "Expand Tabs in Narrow Containers" on the Tabs page.
 * Stretch the tabs across a narrow card with `expand`.
 * @module
 */
import { style, Surface, Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="small" {...styles.card()}>
      <Tabs.Root defaultValue="balances">
        <Tabs.List aria-label="Wallet" expand size="small">
          <Tabs.Tab value="balances">Balances</Tabs.Tab>
          <Tabs.Tab value="activity">Activity</Tabs.Tab>
          <Tabs.Indicator />
        </Tabs.List>
      </Tabs.Root>
    </Surface>
  )
}

namespace styles {
  export const card = style({ width: '16rem !custom' })
}
```

**Don't:** Leave a gap at the end of the row in a narrow card.

```tsx
/**
 * Don't example for "Expand Tabs in Narrow Containers" on the Tabs page.
 * Don't leave a gap at the end of the row in a narrow card.
 * @module
 */
import { style, Surface, Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="small" {...styles.card()}>
      <Tabs.Root defaultValue="balances">
        <Tabs.List aria-label="Wallet" size="small">
          <Tabs.Tab value="balances">Balances</Tabs.Tab>
          <Tabs.Tab value="activity">Activity</Tabs.Tab>
          <Tabs.Indicator />
        </Tabs.List>
      </Tabs.Root>
    </Surface>
  )
}

namespace styles {
  export const card = style({ width: '16rem !custom' })
}
```

## Content

* Use nouns that name the panel's content, such as Overview, Activity, or Settings.
* Keep labels parallel in form and length, such as Send, Receive, and Swap.
* Add an icon only if every tab in the list has one.
* Don't repeat the page title in each label, such as Webhook overview and Webhook settings.

## Accessibility

Tabs follow the [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/), with manual activation by default.

### Semantics

* **Tabs.List (tablist):** Holds the tabs, and needs its own name.
* **Tabs.Tab (tab):** A button. The active tab is selected and points at its panel.
* **Tabs.Panel (tabpanel):** Named by its tab. Hidden panels unmount unless you set `keepMounted`, which find in page requires.
* **Disabled Tabs (aria-disabled):** Reachable with the arrow keys, but can't be activated or shown first.
* **Tabs.Indicator:** Decorative, and ignores pointer events. Under reduced motion, it moves without sliding.

### Keyboard

* **Move into the List (Tab):** Moves focus to the active tab, then to the open panel.
* **Move to the Next Tab (Right Arrow):** Moves focus to the next tab, and wraps at the end.
* **Move to the Previous Tab (Left Arrow):** Moves focus to the previous tab, and wraps at the start.
* **Move to the First Tab (Home):** Moves focus to the first tab.
* **Move to the Last Tab (End):** Moves focus to the last tab.
* **Activate the Tab (Enter or Space):** Activates the focused tab and shows its panel.

Set `activateOnFocus` on `Tabs.List` to activate a tab on focus. Use it only if panels render without delay.

### Focus

* **One Tab Stop:** Only the active tab is in the Tab order. Arrow keys move between tabs.
* **Focusable Panel:** The open panel is focusable, so Tab moves into it even if it holds no controls.

### Your Responsibilities

* **Name the List (SC 4.1.2):** Name the tab list, such as "Sections".

## Related

[ChoiceGroup](/docs/components/choice-group)

Use for one value that changes a view.

[SidebarMenu](/docs/components/sidebar-menu)

Use for navigating between pages.

[Accordion](/docs/components/accordion)

Use for sections you open together.

[Snippet](/docs/components/snippet)

Use for a command with a tab per tool.

[Navigation](/docs/patterns/navigation)

Covers choosing between navigation components.
