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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/tabs.md.

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 content
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} />;
}

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 content
Overview content
Overview content
Card
Overview content
Overview content
Overview content
Segmented
Overview content
Overview content
Overview content
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>
  );
}

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 content
Card
Overview content
Segmented
Overview content
Solid Pill
Overview content
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>
  );
}

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.

Showing this week.
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>
  );
}

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.

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} />;
}

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.

Content 1
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>
  );
}

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.

Content one
Current order: Tab one / Tab two / Tab three
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>
  );
}

Bottom placement

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

Overview content
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} />;
}

API

Tabs API

Configure tab data, the active tab and panel retention.

PropertyTypeDefaultDescription
itemsreadonly TabItem[]RequiredTab items; an empty array hides the component
activeKeystring—Controlled active tab key; update it with onChange.
defaultActiveKeystringFirst enabled itemInitial 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.
blockbooleanfalseFill the available width with equal-width tabs
activationMode'automatic' | 'manual''automatic'Activate on arrow navigation / Enter or Space
destroyInactivebooleanfalseUnmount content when inactive
extraReactNode—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
addLabelstring—Accessible add button label
overflowbooleantrueShow directional scroll buttons on overflow
sortablebooleanfalseEnable sorting; use with onReorder
onReorder(items: TabItem[]) => void—Reordered tabs

TabItem

Define an individual tab key, label and content.

PropertyTypeDefaultDescription
keystringRequiredUnique identifier
labelReactNodeRequiredTab label
childrenReactNode—Optional panel content; omit it to render only the tab bar
disabledbooleanfalseDisable interaction.
iconReactNode—Leading icon
closablebooleanfalseShow a close button; requires onClose