Breadcrumb - Semi Design Next

Demos

How to import

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

Basic Usage

Code

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

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.

Pass the icon with the icon prop of Breadcrumb.Item, for example icon={<IconHome />}.

Code

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

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-solid';
import { Breadcrumb } from '@fibrous/semi-ui-solid';

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 /.

separator takes text or a JSX element, for example separator={<IconArrowRight />}. Breadcrumb.Item provides the same separator prop to override the parent one.

v>=1.16.0

Code

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

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-solid';

const routes = ['首页', '当这个页面标题很长很长很长时需要省略', '详情页'];
const { Text } = Typography;

export default function BreadcrumbDemo() {
    // 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-solid';

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-solid';

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

To customize the ellipsis area in another form, use the renderMore prop. It receives the data of the collapsed items: the route objects with routes, or the props of the Breadcrumb.Item children (read their children and icon where they are shown). It returns what the ellipsis area renders. It takes precedence over moreType when provided.

Code

import { For, Show } from 'solid-js';
import { IconMore } from '@fibrous/semi-icons-solid';
import { Breadcrumb, Popover, type BreadcrumbItemProps, type BreadcrumbRouteProps } from '@fibrous/semi-ui-solid';

const separator = '-'; // 拼接 restItems 用的分隔符

// restItems holds the props of the hidden Breadcrumb.Items, whose children the popover reads only when it opens
const renderMore = (restItems: Array<BreadcrumbRouteProps | BreadcrumbItemProps>) => (
    <Popover
        content={
            <For each={restItems}>
                {(item, index) => (
                    <>
                        {(item as BreadcrumbItemProps).children}
                        <Show when={index() !== restItems.length - 1}>
                            <span style={{ color: 'var(--semi-color-text-2)', 'margin-right': '6px' }}>{separator}</span>
                        </Show>
                    </>
                )}
            </For>
        }
        style={{ padding: '12px' }}
        showArrow
    >
        {/* the more button around the icon is already the Tab stop, so the icon itself is taken out of the Tab order */}
        {(trigger) => <IconMore {...trigger({ tabIndex: -1 })} />}
    </Popover>
);

export default function BreadcrumbDemo() {
    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 }. A route object holds data only: use renderItem to render the content of each item and renderIcon(route, index) to provide its icon. 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.

Code

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

export default function BreadcrumbDemo() {
    const iconRoutes = [
        {
            path: '/',
            href: '/',
        },
        {
            path: '/breadcrumb',
            href: '/zh-CN/navigation/breadcrumb',
            name: 'breadcrumb',
        },
        'with icon',
    ];

    const renderIcon = (route: BreadcrumbRouteProps) => (route.path === '/' ? <IconHome aria-label="首页" size="small" /> : route.path === '/breadcrumb' ? <IconArticle size="small" /> : undefined);

    // 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={iconRoutes} renderIcon={renderIcon} />
            <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`	-
autoCollapse	Whether items beyond maxItemCount collapse automatically.	`boolean`	`true`
compact	Whether the compact size is used, which sets the size of icons and text.	`boolean`	`true`
maxItemCount	Number of levels above which the breadcrumb collapses.	`number`	`4`
moreType	Built-in rendering of the ellipsis area: default or popover. renderMore wins when it is provided.	`MoreType`	`"default"`
onClick	Called on click. With routes it receives the route of the item; with Breadcrumb.Item children it receives `{ name, href }`, where name is the children of the item. The second parameter is the native MouseEvent. Passing it makes items without href operable with Enter as well.	`Type`	-
renderIcon	Renders the icon of each item of routes. The parameters are the route object of the item and its index, counting the collapsed items.	`Type`	-
renderItem	Renders the content of each item with routes. The parameter is the route object of the item, `{ name }` for a string route.	`Type`	-
renderMore	Custom content of the ellipsis area. The parameter holds the data of the collapsed items: the route objects with routes, or the props of the Breadcrumb.Item children. 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.	`Type`	`[]`
separator	Custom separator, either text or a JSX element.	`JSX.Element`	`"/"`
showTooltip	Whether a Tooltip shows for an overflowing title, with its options: width is the truncation width, a number in px or 'auto' for no truncation; ellipsisPos truncates at the end or in the middle; opts are passed to the Tooltip without content. false hides the Tooltip.	`boolean \| showToolTipProps`	`{ width: 150, ellipsisPos: 'end' }`

class, style, ref and other native attributes (such as id and data-*) land on the nav root.

Props

Property	Description	Type	Default
href	Destination of the link, mounted on an a element. The current item does not render as a link.	`string`	-
icon	Icon of the item. A Semi icon without size takes small or default from the compact of Breadcrumb.	`JSX.Element`	-
noLink	Removes the hover and active styles, and the item stops being operable with the keyboard.	`boolean`	-
onClick	Click event, with the same parameters as onClick of Breadcrumb: the route of the item with routes, or `{ name, href }` with children. The second parameter is the native MouseEvent.	`Type`	-
separator	Separator after this item, overriding the separator of Breadcrumb. It is text or a JSX element.	`JSX.Element`	-

class, style, ref and other native attributes (such as id and data-*) land on the outermost span of 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

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.

Properties	Instructions	type	Default
href	Link destinations	`string`	-
name	Routing name	`string`	-
path	Routing path	`string`	-

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