Breadcrumb - Semi Design Next

Demos

How to import

<script setup lang="ts">
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

Breadcrumb.Item can also be imported by name as BreadcrumbItem.

Basic Usage

Code

<script setup lang="ts">
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Breadcrumb>
        <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
        <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
        <Breadcrumb.Item>Default</Breadcrumb.Item>
    </Breadcrumb>
</template>

With Icons

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

Use the #icon slot of Breadcrumb.Item to show an icon.

Code

<script setup lang="ts">
    import { IconArticle, IconHome } from '@fibrous/semi-icons-vue';
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Breadcrumb>
        <Breadcrumb.Item>
            <template #icon>
                <IconHome size="small" />
            </template>
        </Breadcrumb.Item>
        <Breadcrumb.Item>
            <template #icon>
                <IconArticle size="small" />
            </template>
            Breadcrumb
        </Breadcrumb.Item>
        <Breadcrumb.Item>With Icon</Breadcrumb.Item>
    </Breadcrumb>
</template>

Size

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

Code

<script setup lang="ts">
    import { IconHome } from '@fibrous/semi-icons-vue';
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

<template>
    <!-- Several breadcrumbs on one page are told apart by aria-label -->
    <div>
        <Breadcrumb aria-label="紧凑面包屑" compact>
            <Breadcrumb.Item>
                <template #icon>
                    <IconHome size="small" />
                </template>
            </Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Loose</Breadcrumb.Item>
        </Breadcrumb>
        <br />
        <Breadcrumb aria-label="宽松面包屑" :compact="false">
            <Breadcrumb.Item>
                <template #icon>
                    <IconHome size="small" />
                </template>
            </Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Loose</Breadcrumb.Item>
        </Breadcrumb>
    </div>
</template>

Custom Separator

Default separator is /.

separator takes a text separator. For a separator made of nodes, use the #separator slot, which wins over separator. Breadcrumb.Item provides the same separator prop and #separator slot to override the parent one.

v>=1.16.0

Code

<script setup lang="ts">
    import { IconArrowRight } from '@fibrous/semi-icons-vue';
    import { Breadcrumb, Tag } from '@fibrous/semi-ui-vue';
</script>

<template>
    <!-- Several breadcrumbs on one page are told apart by aria-label -->
    <div>
        <Breadcrumb aria-label="文字分隔符" separator=">">
            <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Default</Breadcrumb.Item>
        </Breadcrumb>
        <br />
        <Breadcrumb aria-label="图标分隔符">
            <template #separator>
                <IconArrowRight size="small" />
            </template>
            <Breadcrumb.Item>Semi-ui</Breadcrumb.Item>
            <Breadcrumb.Item>Breadcrumb</Breadcrumb.Item>
            <Breadcrumb.Item>Default</Breadcrumb.Item>
        </Breadcrumb>
        <br />
        <Tag>v&gt;=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>
</template>

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

<script setup lang="ts">
    import { Breadcrumb, Typography } from '@fibrous/semi-ui-vue';

    const routes = ['首页', '当这个页面标题很长很长很长时需要省略', '详情页'];
</script>

<template>
    <!-- Several breadcrumbs on one page are told apart by aria-label -->
    <div>
        <Typography.Text size="small">默认行为</Typography.Text>
        <Breadcrumb aria-label="默认行为" :routes="routes" />
        <br />
        <Typography.Text size="small">省略但不显示Tooltip</Typography.Text>
        <Breadcrumb aria-label="省略但不显示Tooltip" :routes="routes" :showTooltip="false" />
        <br />
        <Typography.Text size="small">不截断</Typography.Text>
        <Breadcrumb aria-label="不截断" :routes="routes" :showTooltip="{ width: 'auto' }" />
        <br />
        <Typography.Text size="small">从标题中间开始省略</Typography.Text>
        <Breadcrumb aria-label="从标题中间开始省略" :routes="routes" :showTooltip="{ ellipsisPos: 'middle' }" />
        <br />
        <Typography.Text size="small">自定义 Tooltip 参数</Typography.Text>
        <Breadcrumb aria-label="自定义 Tooltip 参数" :routes="routes" :showTooltip="{ opts: { position: 'topLeft' } }" />
    </div>
</template>

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

<script setup lang="ts">
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

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

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

<script setup lang="ts">
    import { Breadcrumb } from '@fibrous/semi-ui-vue';
</script>

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

If you want to customize other forms of rendering for the ellipsis area, use the #more="{ restItems }" slot. restItems are the collapsed items without their separators, ready to mount with <component :is>.

Code

<script setup lang="ts">
    import { IconMore } from '@fibrous/semi-icons-vue';
    import { Breadcrumb, Popover, type BreadcrumbItemInfo } from '@fibrous/semi-ui-vue';

    const separator = '-'; // 拼接 restItems 用的分隔符
    const onClick = (item: BreadcrumbItemInfo, e: MouseEvent) => console.log(item, e);
</script>

<template>
    <Breadcrumb @click="onClick">
        <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>
        <template #more="{ restItems }">
            <Popover showArrow :style="{ padding: '12px' }">
                <IconMore tabindex="-1" />
                <template #content>
                    <template v-for="(item, idx) in restItems" :key="idx">
                        <component :is="item" />
                        <span v-if="idx !== restItems.length - 1" :style="{ color: 'var(--semi-color-text-2)', marginRight: '6px' }">{{ separator }}</span>
                    </template>
                </template>
            </Popover>
        </template>
    </Breadcrumb>
</template>

Route Object

Breadcrumb supports passing in an array of strings or route objects consisting of { name, path, href }. Use the #item="{ route, index }" slot to render a custom title, and the #icon="{ route, index }" slot for icons; an empty #icon renders no icon for that item. Breadcrumbs created in this way will also be truncated. routes holds only strings and objects without nodes or functions, and routes[].onClick is not supported: listen with @click of Breadcrumb (onClick of Breadcrumb is a function prop, and whether it is bound decides if items without href are keyboard operable), whose first parameter is the original route.

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

<script setup lang="ts">
    import { IconArticle, IconHome } from '@fibrous/semi-icons-vue';
    import { Breadcrumb, type Route } from '@fibrous/semi-ui-vue';

    const iconRoutes: (Route | string)[] = [{ path: '/', href: '/' }, { path: '/breadcrumb', href: '/zh-CN/navigation/breadcrumb', name: 'breadcrumb' }, 'with icon'];
</script>

<template>
    <!-- Several breadcrumbs on one page are told apart by aria-label -->
    <div>
        <Breadcrumb aria-label="字符串路由" :routes="['Semi-ui', 'Breadcrumb', 'Default']" />
        <br />
        <Breadcrumb aria-label="带图标的路由" :routes="iconRoutes">
            <template #icon="{ index }">
                <IconHome v-if="index === 0" aria-label="首页" size="small" />
                <IconArticle v-else-if="index === 1" size="small" />
            </template>
        </Breadcrumb>
        <br />
        <Breadcrumb aria-label="长标题路由" :routes="['首页', '当这个页面标题很长时需要省略', '详情页']" />
    </div>
</template>

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`	`semiGlobalDefault("Breadcrumb", "activeIndex")`
autoCollapse	Whether items beyond maxItemCount collapse automatically.	`boolean`	`semiDefault("Breadcrumb", "autoCollapse", true)`
compact	Whether the compact size is used.	`boolean`	`semiDefault("Breadcrumb", "compact", true)`
maxItemCount	Number of levels above which the breadcrumb collapses.	`number`	`semiDefault("Breadcrumb", "maxItemCount", 4)`
moreType	Built-in rendering of the ellipsis area: default or popover. The more slot wins when it is provided.	`MoreType`	`semiDefault("Breadcrumb", "moreType", "default")`
routes	Route information as an array of route objects or strings. When it is not empty, the items come from it and the default slot is not rendered.	`(string \| Route)[]`	`semiDefault("Breadcrumb", "routes", [])`
separator	Text separator. The separator slot wins when it is provided.	`string`	`semiDefault("Breadcrumb", "separator", "/")`
showTooltip	Whether a Tooltip shows for an overflowing title, with its options: width is the overflow width, ellipsisPos truncates at the end or in the middle, and opts are passed to the Tooltip without content, with class and style landing on the popup.	`boolean \| ShowTooltipProps`	`semiDefault("Breadcrumb", "showTooltip", DEFAULT_TOOLTIP)`
onClick	Called on click. It is a function prop, bound with @click as usual; passing it makes items without href operable with Enter as well. With routes it receives the route of the item; with Breadcrumb.Item children it receives `{ name, href }`, where name is the text of the item. The second parameter is the native MouseEvent.	`BreadcrumbClick`	`undefined`

Events

Event	Description	Callback parameters
None

Slots

Slot	Description	Scope parameters
default	Children made of Breadcrumb.Item.	`any`
separator	Custom separator. Takes precedence over the separator prop.	`any`
item	With routes, the custom title of each item, with the route and its index as scope parameters.	`BreadcrumbRouteSlotProps`
icon	With routes, the icon of each item, with the route and its index as scope parameters. An empty result renders no icon.	`BreadcrumbRouteSlotProps`
more	Custom ellipsis area. The scope parameter restItems holds the collapsed items without their separators, ready to mount with component.	`BreadcrumbMoreSlotProps`

Exposes

Name	Description	Type
None

class, style, aria-label and other native attributes land on the nav root through attrs.

Props

Property	Description	Type	Default
active	Whether this is the current item, injected by Breadcrumb. The current item has aria-current="page" and does not render as a link.	`boolean`	`undefined`
href	Destination of the link.	`string`	`undefined`
noLink	Removes the hover and active styles.	`boolean`	`undefined`
route	Route object of the item, injected by the routes form of Breadcrumb. It is the first parameter of the click handler.	`Route`	`undefined`
separator	Text separator overriding the one of Breadcrumb. The separator slot wins when it is provided.	`string`	`undefined`
shouldRenderSeparator	Whether the separator renders, injected by Breadcrumb.	`boolean`	`true`
onClick	Called on click, with the same parameters as onClick of Breadcrumb. It is a function prop, bound with @click as usual; passing it makes the item operable with Enter even without href.	`BreadcrumbClick`	`undefined`

Events

Event	Description	Callback parameters
None

Slots

Slot	Description	Scope parameters
default	Text of the item. Strings and numbers are treated as text and take part in truncation and the Tooltip; other nodes render inline as they are.	`any`
icon	Icon of the item.	`any`
separator	Custom separator of this item. Takes precedence over the separator prop.	`any`

Exposes

Name	Description	Type
None

class, style and other native attributes land on the outermost span of the item through attrs.

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`	-
name	Routing name	`string`	-
path	Routing path	`string`	-
noLink	To remove hover and active effect on an item	`boolean`	-
separator	Text separator of the item, used to override parent separator	`string`	-
key	Key of the item	`string \| number`	-

The icon of a route is rendered by the #icon slot, and a custom title by the #item slot. 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