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

# Breadcrumb

导航`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

展示用户当前所处的页面或视图层级。

## 何时使用

当用户需要理解并返回多层级上下文时，将 Breadcrumb 放在页面内容顶部。

**推荐**

- 标签保持简短且易识别。
- 祖先节点使用链接，当前节点使用普通文本。

**避免**

- 不要把 Breadcrumb 当作主导航。

## 代码演示


### 基础用法
```tsx preview
import { Breadcrumb } from '@rockshin/tao-ui';

function BreadcrumbExample() {
  return (
    <Breadcrumb
      items={[
        { title: 'Home', href: '#breadcrumb-example-1' },
        { title: 'Components', href: '#breadcrumb-example-1' },
        { title: 'Breadcrumb' },
      ]}
    />
  );
}

export default BreadcrumbExample;
```

### 分隔符与路径折叠
```tsx preview
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';

function BreadcrumbSeparators() {
  const items = [
    { title: 'Home', href: '#breadcrumb-example-1' },
    { title: 'Settings', href: '#breadcrumb-example-1' },
    { title: 'Profile' },
  ];

  return (
    <Stack gap="md">
      <Breadcrumb separator="/" items={items} />
      <Breadcrumb separator="›" items={items} />
      <Breadcrumb
        maxItems={3}
        items={[
          { title: 'Home', href: '#breadcrumb-example-1' },
          { title: 'Workspace', href: '#breadcrumb-example-1' },
          { title: 'Projects', href: '#breadcrumb-example-1' },
          { title: 'tao-ui', href: '#breadcrumb-example-1' },
          { title: 'Settings' },
        ]}
      />
    </Stack>
  );
}

export default BreadcrumbSeparators;
```

### 禁用项与尺寸
```tsx preview
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';

function BreadcrumbStates() {
  const items = [
    { title: 'Home', href: '#breadcrumb-example-1' },
    { title: 'Archived', href: '#breadcrumb-example-1', disabled: true },
    { title: 'Item' },
  ];

  return (
    <Stack gap="md">
      <TaoProvider size="small">
        <Breadcrumb items={items} />
      </TaoProvider>
      <TaoProvider size="medium">
        <Breadcrumb items={items} />
      </TaoProvider>
      <TaoProvider size="large">
        <Breadcrumb items={items} />
      </TaoProvider>
    </Stack>
  );
}

export default BreadcrumbStates;
```

### 自定义分隔符
通过 `separator` 调整路径分隔符，不改变链接和当前页语义。
```tsx preview
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';

export default function BreadcrumbCustomSeparator() {
  return (
    <Stack gap="md">
      <Breadcrumb
        separator="/"
        items={[
          { title: 'Home', href: '#breadcrumb-example-1' },
          { title: 'Docs', href: '#breadcrumb-example-1' },
          { title: 'Guide' },
        ]}
      />
      <Breadcrumb
        separator="›"
        items={[
          { title: 'Home', href: '#breadcrumb-example-1' },
          { title: 'Settings', href: '#breadcrumb-example-1' },
          { title: 'Profile' },
        ]}
      />
    </Stack>
  );
}
```

### 折叠长路径
`maxItems` 折叠中间路径，点击省略入口查看被隐藏的层级。
```tsx preview
import { Breadcrumb } from '@rockshin/tao-ui';

export default function BreadcrumbCollapsed() {
  return (
    <Breadcrumb
      maxItems={3}
      items={[
        { title: 'Home', href: '#breadcrumb-example-1' },
        { title: 'Group', href: '#breadcrumb-example-1' },
        { title: 'Section', href: '#breadcrumb-example-1' },
        { title: 'Subsection', href: '#breadcrumb-example-1' },
        { title: 'Current Page' },
      ]}
    />
  );
}
```

### 不可用的路径项
将不可跳转的层级标为 `disabled`，当前页仍显示完整名称。
```tsx preview
import { Breadcrumb } from '@rockshin/tao-ui';

export default function BreadcrumbDisabled() {
  return (
    <Breadcrumb
      items={[
        { title: 'Home', href: '#breadcrumb-example-1' },
        { title: 'Archived', href: '#breadcrumb-example-1', disabled: true },
        { title: 'Item' },
      ]}
    />
  );
}
```

### 自定义链接渲染
使用 `itemRender` 接入应用的链接组件，保留普通链接可访问行为。
```tsx preview
import { Breadcrumb } from '@rockshin/tao-ui';

export default function BreadcrumbCustomLink() {
  return (
    <Breadcrumb
      items={[
        { title: 'Home', key: 'home' },
        { title: 'Library', key: 'library' },
        { title: 'Data' },
      ]}
      itemRender={(item, { isLast }) =>
        isLast ? (
          item.title
        ) : (
          // Any custom element works — e.g. a router <Link>. Slot merges the
          // breadcrumb link styles onto it instead of adding another <a>.
          <a href="#breadcrumb-example-1">{item.title}</a>
        )
      }
    />
  );
}
```

### 路径尺寸
用 TaoProvider 的 `size` 匹配紧凑工具栏或宽松页面标题区。
```tsx preview
import { Breadcrumb, Stack, TaoProvider } from '@rockshin/tao-ui';

export default function BreadcrumbSizes() {
  return (
    <Stack gap="md">
      {(['small', 'medium', 'large'] as const).map((size) => (
        <div key={size}>
          <p
            style={{
              fontSize: 13,
              color: 'var(--tao-color-text-secondary)',
              marginBottom: 4,
            }}
          >
            {size}
          </p>
          <TaoProvider size={size}>
            <Breadcrumb
              items={[
                { title: 'Home', href: '#breadcrumb-example-1' },
                { title: 'List', href: '#breadcrumb-example-1' },
                { title: 'Detail' },
              ]}
            />
          </TaoProvider>
        </div>
      ))}
    </Stack>
  );
}
```

## API


### [#](#breadcrumb)Breadcrumb



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| items | Breadcrumb path, root first. The last item renders as the current page. | `BreadcrumbItemType[]` **(必填)** | `-` |
| separator | Separator between items. Defaults to a chevron, like shadcn. | `ReactNode` | `-` |
| maxItems | Collapse the middle of long paths into an ellipsis once the number of
items exceeds this value. Shows the first item and the last
`maxItems - 1` items. | `number | undefined` | `-` |
| itemRender | Custom renderer for an item's content. Return a React element (e.g. a
router `<Link>`) and its props are merged onto the breadcrumb link via
Radix Slot — no extra `<a>` wrapper is added. | `((item: BreadcrumbItemType, info: { index: number; isLast: boolean; items: BreadcrumbItemType[]; }) => ReactNode) | undefined` | `-` |
| className | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

