> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/tabs.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Tabs

Switch content within one region.


## Basic usage

Define labels and content with `items`; select a tab to switch panels. Unselected line tabs use body text color, then the lighter theme color on hover and the darker theme color when pressed, with a default color transition of 300ms. Selected tabs use the theme color and an underline spanning the tab width. A continuous divider runs along the bottom of the tab bar.


Overview

Settings

Overview content

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tabs/basic.tsx"
import { Tabs } from '@ifhover/leaf-ui';

const items = [
  { key: 'overview', label: 'Overview', children: 'Overview content' },
  { key: 'settings', label: 'Settings', children: 'Settings content' },
];

export function TabsBasic() {
  return <Tabs aria-label="Content categories" items={items} />;
}
```

Expand code


## Examples

### Sizes

Use `size` to set the tab control size. Small and medium line tabs share a font size and differ in vertical spacing; large line tabs increase both the font size and vertical spacing. Each row shows one appearance, with columns comparing small, medium and large sizes. Scroll horizontally on narrow screens.


SmallMediumLargeLine

Overview

Settings

Overview content

Overview

Settings

Overview content

Overview

Settings

Overview content

Card

Overview

Settings

Overview content

Overview

Settings

Overview content

Overview

Settings

Overview content

Segmented

Overview

Settings

Overview content

Overview

Settings

Overview content

Overview

Settings

Overview content

sizes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tabs/sizes.tsx"
import { Grid, ScrollArea, Tabs, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const items = [
  { key: 'overview', label: 'Overview', children: 'Overview content' },
  { key: 'settings', label: 'Settings', children: 'Settings content' },
];

const sizes = [
  { value: 'sm', label: 'Small' },
  { value: 'md', label: 'Medium' },
  { value: 'lg', label: 'Large' },
] as const;

const appearances = [
  { value: 'line', label: 'Line' },
  { value: 'card', label: 'Card' },
  { value: 'segmented', label: 'Segmented' },
] as const;

export function TabsSizes() {
  return (
    <ScrollArea orientation="horizontal" aria-label="Tab appearance and size comparison">
      <Grid
        columns={4}
        gap={24}
        align="center"
        style={{ gridTemplateColumns: 'max-content repeat(3, minmax(240px, 1fr))' }}
      >
        <span aria-hidden="true" />
        {sizes.map((size) => (
          <Text key={size.value} tone="muted">
            {size.label}
          </Text>
        ))}
        {appearances.map((appearance) => (
          <Fragment key={appearance.value}>
            <Text tone="muted">{appearance.label}</Text>
            {sizes.map((size) => (
              <Tabs
                key={size.value}
                aria-label={`${size.label} ${appearance.label}`}
                size={size.value}
                type={appearance.value}
                items={items}
              />
            ))}
          </Fragment>
        ))}
      </Grid>
    </ScrollArea>
  );
}
```

Expand code

### Appearances

Use `type` to choose the tab appearance. For `card` and `segmented` tabs, configure `tone` (`soft` or `solid`) and `shape` (`default` or `pill`).


Line

Overview

Settings

Overview content

Card

Overview

Settings

Overview content

Segmented

Overview

Settings

Overview content

Solid Pill

Overview

Settings

Overview content

appearances.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tabs/appearances.tsx"
import { Space, Tabs, Text } from '@ifhover/leaf-ui';

const items = [
  { key: 'overview', label: 'Overview', children: 'Overview content' },
  { key: 'settings', label: 'Settings', children: 'Settings content' },
];

export function TabsAppearances() {
  return (
    <Space direction="vertical" align="stretch" size="lg">
      <Space direction="vertical" align="stretch" size="sm">
        <Text tone="muted">Line</Text>
        <Tabs aria-label="Line" type="line" items={items} />
      </Space>
      <Space direction="vertical" align="stretch" size="sm">
        <Text tone="muted">Card</Text>
        <Tabs aria-label="Card" type="card" items={items} />
      </Space>
      <Space direction="vertical" align="stretch" size="sm">
        <Text tone="muted">Segmented</Text>
        <Tabs aria-label="Segmented" type="segmented" items={items} />
      </Space>
      <Space direction="vertical" align="stretch" size="sm">
        <Text tone="muted">Solid Pill</Text>
        <Tabs aria-label="Solid Pill" type="segmented" tone="solid" shape="pill" items={items} />
      </Space>
    </Space>
  );
}
```

Expand code

### View switching

Omit item `children` to render only the tab bar. Use `activeKey` and `onChange` to switch content outside the component.

Arrow keys activate the next enabled tab by default; Home / End move to the first / last enabled tab. With `activationMode="manual"`, arrow keys move focus and Enter or Space activates the focused tab.


Week

Month

Year

Showing this week.

view-switcher.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tabs/view-switcher.tsx"
import { Flex, Tabs, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TabsViewSwitcher() {
  const [view, setView] = useState('week');
  return (
    <Flex direction="column" gap="md">
      <Tabs
        type="card"
        block
        aria-label="Statistics period"
        activeKey={view}
        onChange={setView}
        items={[
          { key: 'week', label: 'Week' },
          { key: 'month', label: 'Month' },
          { key: 'year', label: 'Year', disabled: true },
        ]}
      />
      <Text role="status">{view === 'week' ? 'Showing this week.' : 'Showing this month.'}</Text>
    </Flex>
  );
}
```

Expand code

### Preserved input state

Content mounts on first visit. Visited panels and their input state are kept by default; set `destroyInactive` to unmount content when leaving.


Draft

Other content

preserved.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tabs/preserved.tsx"
import { Input, Tabs } from '@ifhover/leaf-ui';

const items = [
  {
    key: 'draft',
    label: 'Draft',
    children: <Input aria-label="Draft content" placeholder="Type here, then switch tabs" />,
  },
  { key: 'preview', label: 'Other content', children: 'Return to Draft to check your input.' },
];

export function TabsPreserved() {
  return <Tabs aria-label="Preserved input state" items={items} />;
}
```

Expand code

### Adding and closing tabs

`onAdd` and `onClose` report requests; update `items` in the application. When `items` is empty, the whole component, including its add button, is hidden. Keep an external action to restore the list.


Tab 1

Tab 2

Content 1

Clear tabsRestore tabs

closable.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tabs/closable.tsx"
import { Button, Flex, type TabItem, Tabs, Text } from '@ifhover/leaf-ui';
import { useRef, useState } from 'react';

const initialItems: TabItem[] = [
  { key: '1', label: 'Tab 1', children: 'Content 1', closable: true },
  { key: '2', label: 'Tab 2', children: 'Content 2', closable: true },
];

export function TabsClosable() {
  const nextId = useRef(3);
  const [items, setItems] = useState(initialItems);
  const addTab = () => {
    const key = String(nextId.current++);
    setItems((list) => [
      ...list,
      { key, label: `Tab ${key}`, children: `Content ${key}`, closable: true },
    ]);
  };
  return (
    <Flex direction="column" gap="md">
      <Tabs
        aria-label="Editable tabs"
        items={items}
        onAdd={addTab}
        addLabel="Add tab"
        onClose={(key) => setItems((list) => list.filter((item) => item.key !== key))}
      />
      {items.length === 0 && (
        <Text role="status" tone="muted">
          No tabs. Restore them to add more.
        </Text>
      )}
      <Flex gap="sm" wrap>
        <Button variant="outline" disabled={items.length === 0} onClick={() => setItems([])}>
          Clear tabs
        </Button>
        <Button variant="outline" onClick={() => setItems(initialItems)}>
          Restore tabs
        </Button>
      </Flex>
    </Flex>
  );
}
```

Expand code

### Sorting tabs

Enable `sortable` and store the items returned by `onReorder`. Drag a handle to reorder, or focus it and use Space, arrow keys, then Space to confirm; Escape cancels.


Tab one

Tab two

Tab three

Content one

Current order: Tab one / Tab two / Tab three

Restore order

extensions.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tabs/extensions.tsx"
import { Button, Flex, type TabItem, Tabs, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const initialItems: TabItem[] = [
  { key: 'one', label: 'Tab one', children: 'Content one' },
  { key: 'two', label: 'Tab two', children: 'Content two' },
  { key: 'three', label: 'Tab three', children: 'Content three' },
];

export function ExtensionDemo() {
  const [items, setItems] = useState(initialItems);
  return (
    <Flex direction="column" gap="md">
      <Tabs aria-label="Sortable tabs" items={items} sortable onReorder={setItems} />
      <Text role="status" tone="muted">
        Current order: {items.map((item) => item.label).join(' / ')}
      </Text>
      <Flex>
        <Button variant="outline" onClick={() => setItems(initialItems)}>
          Restore order
        </Button>
      </Flex>
    </Flex>
  );
}
```

Expand code

### Bottom placement

Set `placement="bottom"` to place the tabs below the content.


Overview

Settings

Overview content

capabilities.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tabs/capabilities.tsx"
import { Tabs } from '@ifhover/leaf-ui';

const items = [
  { key: 'overview', label: 'Overview', children: 'Overview content' },
  { key: 'settings', label: 'Settings', children: 'Settings content' },
];

export function Capabilities() {
  return <Tabs aria-label="Bottom tabs" placement="bottom" items={items} />;
}
```

Expand code


## API

### Tabs API

Configure tab data, the active tab and panel retention.

| Property           | Type                                                          | Default            | Description                                                                                    |
| ------------------ | ------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `items`            | `readonly `[`TabItem`](#tabitem)`[]`                          | Required           | Tab items; an empty array hides the component                                                  |
| `activeKey`        | `string`                                                      | —                  | Controlled active tab key; update it with onChange.                                            |
| `defaultActiveKey` | `string`                                                      | First enabled item | Initial tab key in uncontrolled mode; later changes do not reset the selection.                |
| `onChange`         | `(key: string) => void`                                       | —                  | Active key change                                                                              |
| `type`             | `'line' \| 'card' \| 'segmented'`                             | `'line'`           | Tab appearance                                                                                 |
| `tone`             | `'soft' \| 'solid'`                                           | `'soft'`           | Selection highlight tone for card and segmented tabs: soft primary tint or solid primary fill. |
| `shape`            | `'default' \| 'pill'`                                         | `'default'`        | Tab corner shape for card and segmented tabs: rounded rectangle or pill.                       |
| `placement`        | `'top' \| 'bottom'`                                           | `'top'`            | Tab bar placement                                                                              |
| `size`             | `'sm' \| 'md' \| 'lg'`                                        | `'md'`             | Tab size.                                                                                      |
| `block`            | `boolean`                                                     | `false`            | Fill the available width with equal-width tabs                                                 |
| `activationMode`   | `'automatic' \| 'manual'`                                     | `'automatic'`      | Activate on arrow navigation / Enter or Space                                                  |
| `destroyInactive`  | `boolean`                                                     | `false`            | Unmount content when inactive                                                                  |
| `extra`            | `ReactNode`                                                   | —                  | Extra tab bar content                                                                          |
| `onClose`          | `(key: string, event: MouseEvent<HTMLButtonElement>) => void` | —                  | Close request: remove the item in the application; preventDefault cancels selection changes    |
| `onAdd`            | `() => void`                                                  | —                  | Add tab; enables add button                                                                    |
| `addLabel`         | `string`                                                      | —                  | Accessible add button label                                                                    |
| `overflow`         | `boolean`                                                     | `true`             | Show directional scroll buttons on overflow                                                    |
| `sortable`         | `boolean`                                                     | `false`            | Enable sorting; use with onReorder                                                             |
| `onReorder`        | `(items: `[`TabItem`](#tabitem)`[]) => void`                  | —                  | Reordered tabs                                                                                 |

### TabItem

Define an individual tab key, label and content.

| Property   | Type        | Default  | Description                                                |
| ---------- | ----------- | -------- | ---------------------------------------------------------- |
| `key`      | `string`    | Required | Unique identifier                                          |
| `label`    | `ReactNode` | Required | Tab label                                                  |
| `children` | `ReactNode` | —        | Optional panel content; omit it to render only the tab bar |
| `disabled` | `boolean`   | `false`  | Disable interaction.                                       |
| `icon`     | `ReactNode` | —        | Leading icon                                               |
| `closable` | `boolean`   | `false`  | Show a close button; requires onClose                      |
