Breadcrumb - Semi Design Next

Demos

How to import

import { Breadcrumb } from '@fibrous/semi-ui-react';

Basic Usage

Code

import { Breadcrumb } from '@fibrous/semi-ui-react';

export default function BreadcrumbDemo() {
    return (
        <Breadcrumb>
            <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Default</Breadcrumb.Item>
        </Breadcrumb>
    );
}

With Icons

A level can show an icon only, or an icon together with text.

Code

import { IconHome, IconArticle } from '@fibrous/semi-icons-react';
import { Breadcrumb } from '@fibrous/semi-ui-react';

export default function BreadcrumbDemo() {
    return (
        <Breadcrumb>
            <Breadcrumb.Item icon={<IconHome size="small" />} />
            <Breadcrumb.Item icon={<IconArticle size="small" />}>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>With Icon</Breadcrumb.Item>
        </Breadcrumb>
    );
}

Size

You can set the compact property to false to increase the size of icons and texts.

Code

import { IconHome } from '@fibrous/semi-icons-react';
import { Breadcrumb } from '@fibrous/semi-ui-react';

export default function BreadcrumbDemo() {
    // Several breadcrumbs on one page are told apart by aria-label
    return (
        <div>
            <Breadcrumb compact aria-label="紧凑面包屑">
                <Breadcrumb.Item icon={<IconHome size="small" />} />
                <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
                <Breadcrumb.Item>Loose</Breadcrumb.Item>
            </Breadcrumb>
            <br />
            <Breadcrumb compact={false} aria-label="宽松面包屑">
                <Breadcrumb.Item icon={<IconHome size="small" />} />
                <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
                <Breadcrumb.Item>Loose</Breadcrumb.Item>
            </Breadcrumb>
        </div>
    );
}

Custom Separator

Default separator is /.

v>=1.16.0

Code

import { IconArrowRight } from '@fibrous/semi-icons-react';
import { Breadcrumb, Tag } from '@fibrous/semi-ui-react';

export default function BreadcrumbDemo() {
    // Several breadcrumbs on one page are told apart by aria-label
    return (
        <div>
            <Breadcrumb separator=">" aria-label="文字分隔符">
                <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
                <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
                <Breadcrumb.Item>Default</Breadcrumb.Item>
            </Breadcrumb>
            <br />
            <Breadcrumb separator={<IconArrowRight size="small" />} aria-label="图标分隔符">
                <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
                <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
                <Breadcrumb.Item>Default</Breadcrumb.Item>
            </Breadcrumb>
            <br />
            <Tag>{`v>=1.16.0`}</Tag>
            <br />
            <Breadcrumb aria-label="单项分隔符">
                <Breadcrumb.Item separator=":">Semi-ui</Breadcrumb.Item>
                <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
                <Breadcrumb.Item>Default</Breadcrumb.Item>
            </Breadcrumb>
        </div>
    );
}

Truncated Logic

The truncation happens if the text is overflowed. Default max-width is set to 150px. You could use showTooltip to customize ellipsis behavior. A number as the child of Breadcrumb.Item (including 0) is treated as text and takes part in truncation and the Tooltip.

默认行为
省略但不显示Tooltip
不截断
从标题中间开始省略
自定义 Tooltip 参数

Code

import { Breadcrumb, Typography } from '@fibrous/semi-ui-react';

export default function BreadcrumbDemo() {
    const routes = ['首页', '当这个页面标题很长很长很长时需要省略', '详情页'];
    const { Text } = Typography;
    // Several breadcrumbs on one page are told apart by aria-label
    return (
        <>
            <Text size="small">默认行为</Text>
            <Breadcrumb routes={routes} aria-label="默认行为" />
            <br />
            <Text size="small">省略但不显示Tooltip</Text>
            <Breadcrumb showTooltip={false} routes={routes} aria-label="省略但不显示Tooltip" />
            <br />
            <Text size="small">不截断</Text>
            <Breadcrumb showTooltip={{ width: 'auto' }} routes={routes} aria-label="不截断" />
            <br />
            <Text size="small">从标题中间开始省略</Text>
            <Breadcrumb showTooltip={{ ellipsisPos: 'middle' }} routes={routes} aria-label="从标题中间开始省略" />
            <br />
            <Text size="small">自定义 Tooltip 参数</Text>
            <Breadcrumb showTooltip={{ opts: { position: 'topLeft' } }} routes={routes} aria-label="自定义 Tooltip 参数" />
        </>
    );
}

When the number of levels exceeds maxItemCount (default 4), the second level through level n-m+1 (counted from 1, and never past the penultimate level) are replaced by ellipsis by default, where n is the number of levels and m is maxItemCount. You can click the ellipsis to reveal all levels. The first, the current and the last level always stay visible. When activeIndex points at a level that would be collapsed, the current level stays visible instead: of the candidates before and after it, the run with more levels is collapsed (the one before it on a tie), so there is still only one ellipsis. With no candidates nothing is collapsed, and more levels than maxItemCount may show. You could use maxItemCount to set the number exceeded to trigger auto collapse.

Code

import { Breadcrumb } from '@fibrous/semi-ui-react';

export default function BreadcrumbDemo() {
    return (
        <Breadcrumb>
            <Breadcrumb.Item>首页</Breadcrumb.Item>
            <Breadcrumb.Item>当层级很多的时候</Breadcrumb.Item>
            <Breadcrumb.Item>又一层</Breadcrumb.Item>
            <Breadcrumb.Item>再一层</Breadcrumb.Item>
            <Breadcrumb.Item>上上一层</Breadcrumb.Item>
            <Breadcrumb.Item>上一层</Breadcrumb.Item>
            <Breadcrumb.Item>详情页</Breadcrumb.Item>
        </Breadcrumb>
    );
}

Custom Ellipsis

There are two ellipsis area rendering types provided inside the component. You can set and select the desired rendering type through moreType. The optional values of moreType are default and popover.

Code

import { Breadcrumb } from '@fibrous/semi-ui-react';

export default function BreadcrumbDemo() {
    return (
        <Breadcrumb moreType="popover">
            <Breadcrumb.Item>首页</Breadcrumb.Item>
            <Breadcrumb.Item>当层级很多的时候</Breadcrumb.Item>
            <Breadcrumb.Item>又一层</Breadcrumb.Item>
            <Breadcrumb.Item>再一层</Breadcrumb.Item>
            <Breadcrumb.Item>上上一层</Breadcrumb.Item>
            <Breadcrumb.Item>上一层</Breadcrumb.Item>
            <Breadcrumb.Item>详情页</Breadcrumb.Item>
        </Breadcrumb>
    );
}

If you want to customize other forms of rendering for the ellipsis area, you can use the renderMore() method.

Code

import React, { type ReactNode } from 'react';
import { IconMore } from '@fibrous/semi-icons-react';
import { Breadcrumb, Popover } from '@fibrous/semi-ui-react';

export default function BreadcrumbDemo() {
    const separator = '-'; // 拼接 restItem 用的分隔符
    const renderMore = (restItem: ReactNode[]) => {
        const content = (
            <>
                {restItem.map((item: ReactNode, idx: number) => (
                    <React.Fragment key={`restItem-${idx}`}>
                        {item}
                        {idx !== restItem.length - 1 && <span style={{ color: 'var(--semi-color-text-2)', marginRight: '6px' }}>{separator}</span>}
                    </React.Fragment>
                ))}
            </>
        );
        return (
            <Popover content={content} style={{ padding: 12 }} showArrow>
                <IconMore tabIndex={-1} />
            </Popover>
        );
    };
    return (
        <Breadcrumb renderMore={renderMore} onClick={(item, e) => console.log(item, e)}>
            <Breadcrumb.Item>首页</Breadcrumb.Item>
            <Breadcrumb.Item>当层级很多的时候</Breadcrumb.Item>
            <Breadcrumb.Item>又一层</Breadcrumb.Item>
            <Breadcrumb.Item>再一层</Breadcrumb.Item>
            <Breadcrumb.Item>上上一层</Breadcrumb.Item>
            <Breadcrumb.Item>上一层</Breadcrumb.Item>
            <Breadcrumb.Item>详情页</Breadcrumb.Item>
        </Breadcrumb>
    );
}

Route Object

Breadcrumb supports passing in an array of strings or route objects consisting of { name, path, href, icon }. You can also use renderItem to render React.nodes. Breadcrumbs created in this way will also be truncated.

name: Name displayed, default with an empty string. When route passed in is a string only, it is set to name property.
path: Routing path.
href: Link destination and is mounted on the <a> tag.
icon: Icon displayed.

Code

import { IconHome, IconArticle } from '@fibrous/semi-icons-react';
import { Breadcrumb } from '@fibrous/semi-ui-react';

export default function BreadcrumbDemo() {
    // Several breadcrumbs on one page are told apart by aria-label
    return (
        <div>
            <Breadcrumb routes={['Semi-ui', 'Breadcrumb', 'Default']} aria-label="字符串路由" />
            <br />
            <Breadcrumb
                aria-label="带图标的路由"
                routes={[
                    {
                        path: '/',
                        href: '/',
                        icon: <IconHome aria-label="首页" size="small" />,
                    },
                    {
                        path: '/breadcrumb',
                        href: '/zh-CN/navigation/breadcrumb',
                        name: 'breadcrumb',
                        icon: <IconArticle size="small" />,
                    },
                    'with icon',
                ]}
            />
            <br />
            <Breadcrumb routes={['首页', '当这个页面标题很长时需要省略', '详情页']} aria-label="长标题路由" />
        </div>
    );
}

API reference

Props

Property	Description	Type	Default
activeIndex	Controlled index of the current item, counted from 0. The last item is current when omitted.	`number`	-
aria-label	Accessible name of the navigation. The locale text is used when omitted.	`React.AriaAttributes['aria-label']`	-
autoCollapse	Whether the levels beyond `maxItemCount` collapse into an ellipsis automatically.	`boolean`	`true`
children	`Breadcrumb.Item` children. children are not rendered when `routes` is not empty.	`ReactNode`	-
className	Class name of the root nav element.	`string`	-
compact	Whether the compact size is used, which sets the size of text and Semi icons.	`boolean`	`true`
maxItemCount	Number of levels above which the breadcrumb collapses. The first, current and last levels stay visible.	`number`	`4`
moreType	Built-in rendering of the ellipsis area, `default` or `popover`. `renderMore` wins when it is provided.	`MoreType`	`"default"`
onClick	Called when an item is clicked. With `routes` it receives the route object of the item, `{ name }` for a string route; with `Breadcrumb.Item` children it receives `{ name, href }`, where `name` is the children of the item. The second parameter is the native MouseEvent. Once it is passed, items without `href`, without `noLink` and not current can also be operated with Enter.	`Type`	-
ref	Ref of the root nav element.	`Type`	-
renderItem	Renders the content of each item with `routes`. The argument is the route object of the item, `{ name }` for a string route.	`Type`	-
renderMore	Renders the content of the ellipsis area. The argument holds the collapsed items without their separators. It wins over `moreType` when provided.	`Type`	-
routes	Route information as an array of route objects or strings. When it is not empty, the items come from it and children are not rendered. The fields of a route object are listed under Route below.	`Type`	`[]`
separator	Custom separator, either text or a ReactNode.	`React.ReactNode`	`"/"`
showTooltip	Whether a Tooltip shows for an overflowing title, with its options: `width` is the truncation width in px, `ellipsisPos` truncates at the `end` or in the `middle`, and `opts` are passed to the Tooltip without `content`, defaulting to `{ autoAdjustOverflow: true, position: 'top' }`. `false` hides the Tooltip, and the title is still truncated at `width`.	`boolean \| showToolTipProps`	`{ width: 150, ellipsisPos: 'end' }`
style	Inline style of the root nav element.	`React.CSSProperties`	-

id, data-* and other native attributes land on the root nav element.

Props

Property	Description	Type	Default
active	Whether the item is the current one. `Breadcrumb` sets it, and callers should not pass it.	`boolean`	-
children	Title content. Numbers and strings are truncated with a Tooltip, and other nodes render as they are.	`ReactNode`	-
className	Class name of the outer span that wraps the item.	`string`	-
href	Destination of the link, mounted on an a element. The current item does not render as a link.	`string`	-
icon	Icon before the title. A Semi icon without `size` takes `small` or `default` from `compact` of Breadcrumb.	`React.ReactNode`	-
noLink	Removes the hover and active styles. An item without `href` is no longer operable with the keyboard.	`boolean`	-
onClick	Called on click, with the same parameters as `onClick` of Breadcrumb: the route object of the item with `routes`, or `{ name, href }` with children. The second parameter is the native MouseEvent.	`Type`	-
ref	Ref of the outer span that wraps the item.	`Type`	-
route	The route object of the item when `Breadcrumb` renders it from `routes`, passed to `onClick`. Callers should not pass it.	`RouteProps`	-
separator	Separator after this item. It overrides `separator` of Breadcrumb and can be text or a ReactNode.	`React.ReactNode`	-
shouldRenderSeparator	Whether the separator after this item renders. `Breadcrumb` sets it by position and collapse state, and callers should not pass it. It defaults to true.	`boolean`	-
style	Inline style of the outer span that wraps the item.	`CSSProperties`	-

id, data-* and other native attributes land on the outer span that wraps the item.

A key set by the caller on a Breadcrumb.Item is kept, so the state of a keyed Item follows its key when the items are reordered. Only Breadcrumb.Item children receive active and shouldRenderSeparator; other elements and text render as they are.

Route

Properties	Instructions	type	Default
href	Link destinations	string	-
icon	Displayed icon	ReactNode	-
name	Routing name	string	-
path	Routing path	string	-

A route can also carry noLink, separator and onClick, which work like the props of the same name on Breadcrumb.Item. data-* fields are passed to the item.

Accessibility

Breadcrumb supports the aria-label props to indicate the function of the Breadcrumb
Breadcrumb will set aria-current='page' for the current item

Content Guidelines

Each page link should be short and clearly reflect the location or entity it links to
Write in sentence case

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.

Sass variable	Value	Usage
$transition_duration-breadcrumb_link-text	var(--semi-transition_duration-none)	面包屑文字-文字-动画持续时间
$transition_function-breadcrumb_link-text	var(--semi-transition_function-easeIn)	面包屑文字-文字-过渡曲线
$transition_delay-breadcrumb_link-text	var(--semi-transition_delay-none)	面包屑文字-文字-延迟时间
$transform_scale-breadcrumb_link-text	var(--semi-transform_scale-none)	面包屑文字-放大
$spacing-breadcrumb_item_wrap-marginY	$spacing-extra-tight
$spacing-breadcrumb_item_wrap-marginRight	$spacing-extra-tight
$spacing-breadcrumb_item-marginRight	$spacing-extra-tight
$spacing-breadcrumb_item_text-marginLeft	$spacing-extra-tight
$spacing-breadcrumb_restItem-marginRight	$spacing-tight
$color-breadcrumb_default-text-default	var(--semi-color-text-2)
$color-breadcrumb_default-text-hover	var(--semi-color-link)
$color-breadcrumb_default-text-active	var(--semi-color-link-hover)
$color-breadcrumb_active-text-default	var(--semi-color-text-0)
$color-breadcrumb_active-text-active	var(--semi-color-text-0)
$color-breadcrumb_sepearator_default-icon-default	var(--semi-color-text-2)
$color-breadcrumb-restItem-text-default	var(--semi-color-text-2)
$font-breadcrumb_default-fontWeight	$font-weight-regular
$font-breadcrumb_active-fontWeight	$font-weight-bold
$font-breadcrumb_compact-fontSize	$font-size-small
$font-breadcrumb_loose-fontSize	$font-size-regular