Demos
How to import
<script lang="ts">
import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>
Svelte has no Breadcrumb.Item; each item is described by routes.
Basic Usage
Code
<script lang="ts">
import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>
<Breadcrumb routes={['Semi-ui', 'Breadcrumb', 'Default']} />With Icons
A level can show an icon only, or an icon together with text.
Use the icon snippet. Its parameter carries the route and index of the item, plus the size and class to pass on to the icon: <IconHome {size} class={className} />. Pick the icon by index; an item without an icon renders nothing. For an icon-only item, set name to an empty string and give the icon an aria-label.
Code
<script lang="ts">
import { IconArticle, IconHome } from '@fibrae/semi-icons-svelte';
import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>
<Breadcrumb routes={['', 'Breadcrumb', 'With Icon']}>
{#snippet icon({ class: className, index, size })}
{#if index === 0}
<IconHome aria-label="Home" class={className} {size} />
{:else if index === 1}
<IconArticle class={className} {size} />
{/if}
{/snippet}
</Breadcrumb>Size
You can set the compact property to false to increase the size of icons and texts.
Code
<script lang="ts">
import { IconHome } from '@fibrae/semi-icons-svelte';
import { Breadcrumb, type BreadcrumbIconContext } from '@fibrae/semi-ui-svelte';
const routes = ['', 'Breadcrumb', 'Loose'];
</script>
{#snippet icon({ class: className, index, size }: BreadcrumbIconContext)}
{#if index === 0}
<IconHome aria-label="Home" class={className} {size} />
{/if}
{/snippet}
<!-- Several breadcrumbs on one page are told apart by aria-label -->
<div>
<Breadcrumb aria-label="紧凑面包屑" compact {icon} {routes} />
<br />
<Breadcrumb aria-label="宽松面包屑" compact={false} {icon} {routes} />
</div>Custom Separator
Default separator is /.
separator takes text; for a separator made of nodes, use the separator snippet. A single route can carry a separator field to override the shared one.
Code
<script lang="ts">
import { IconArrowRight } from '@fibrae/semi-icons-svelte';
import { Breadcrumb, Tag } from '@fibrae/semi-ui-svelte';
</script>
<!-- Several breadcrumbs on one page are told apart by aria-label -->
<div>
<Breadcrumb aria-label="文字分隔符" routes={['Semi-ui', 'Breadcrumb', 'Default']} separator=">" />
<br />
<Breadcrumb aria-label="图标分隔符" routes={['Semi-ui', 'Breadcrumb', 'Default']}>
{#snippet separator()}
<IconArrowRight size="small" />
{/snippet}
</Breadcrumb>
<br />
<Tag>v>=1.16.0</Tag>
<br />
<Breadcrumb aria-label="单项分隔符" routes={[{ name: 'Semi-ui', separator: ':' }, 'Breadcrumb', 'Default']} />
</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.
The title comes from the name of the route and is treated as text, taking part in truncation and the Tooltip; the content of the item snippet renders inline and is not truncated.
省略但不显示Tooltip
不截断
从标题中间开始省略
自定义 Tooltip 参数
Code
<script lang="ts">
import { Breadcrumb, TypographyText } from '@fibrae/semi-ui-svelte';
const routes = ['首页', '当这个页面标题很长很长很长时需要省略', '详情页'];
</script>
<!-- Several breadcrumbs on one page are told apart by aria-label -->
<div>
<TypographyText size="small">默认行为</TypographyText>
<Breadcrumb aria-label="默认行为" {routes} />
<br />
<TypographyText size="small">省略但不显示Tooltip</TypographyText>
<Breadcrumb aria-label="省略但不显示Tooltip" {routes} showTooltip={false} />
<br />
<TypographyText size="small">不截断</TypographyText>
<Breadcrumb aria-label="不截断" {routes} showTooltip={{ width: 'auto' }} />
<br />
<TypographyText size="small">从标题中间开始省略</TypographyText>
<Breadcrumb aria-label="从标题中间开始省略" {routes} showTooltip={{ ellipsisPos: 'middle' }} />
<br />
<TypographyText size="small">自定义 Tooltip 参数</TypographyText>
<Breadcrumb aria-label="自定义 Tooltip 参数" {routes} showTooltip={{ opts: { position: 'topLeft' } }} />
</div>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 lang="ts">
import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>
<Breadcrumb routes={['首页', '当层级很多的时候', '又一层', '再一层', '上上一层', '上一层', '详情页']} />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 lang="ts">
import { Breadcrumb } from '@fibrae/semi-ui-svelte';
</script>
<Breadcrumb moreType="popover" routes={['首页', '当层级很多的时候', '又一层', '再一层', '上上一层', '上一层', '详情页']} />To customize the ellipsis area in another form, use the more snippet. Its parameter restItems holds the collapsed items as { route, index }. It takes precedence over moreType when provided.
Code
<script lang="ts">
import { IconMore } from '@fibrae/semi-icons-svelte';
import { Breadcrumb, Popover, type BreadcrumbRoute } from '@fibrae/semi-ui-svelte';
// Joins the collapsed items in the popup
const separator = '-';
const onClick = (route: BreadcrumbRoute, event: MouseEvent) => console.log(route, event);
</script>
<Breadcrumb {onClick} routes={['首页', '当层级很多的时候', '又一层', '再一层', '上上一层', '上一层', '详情页']}>
{#snippet more({ restItems })}
<Popover showArrow style="padding: 12px">
{#snippet child({ props })}<IconMore {...props} tabindex={-1} />{/snippet}
{#snippet content()}
{#each restItems as { route, index }, i (index)}
<span>{route.name}</span>
{#if i < restItems.length - 1}
<span style="color: var(--semi-color-text-2); margin-inline-end: 6px">{separator}</span>
{/if}
{/each}
{/snippet}
</Popover>
{/snippet}
</Breadcrumb>Route Object
Breadcrumb takes an array of strings or route objects consisting of { name, path, href } through routes; there is no Breadcrumb.Item. Use the item snippet to render a custom title (inline, without truncation) and the icon snippet for icons; both receive the route and index of the item. A route holds data only, and routes[].onClick is not supported: use onClick of Breadcrumb instead (it is a function prop, and whether it is passed decides if items without href are keyboard operable). Its first parameter is the route of the item, and a string route arrives as { name }.
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 lang="ts">
import { IconArticle, IconHome } from '@fibrae/semi-icons-svelte';
import { Breadcrumb, type BreadcrumbRoute } from '@fibrae/semi-ui-svelte';
const iconRoutes: (BreadcrumbRoute | string)[] = [{ path: '/', href: '/' }, { path: '/breadcrumb', href: '/zh-CN/navigation/breadcrumb', name: 'breadcrumb' }, 'with icon'];
</script>
<!-- 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}>
{#snippet icon({ class: className, index, size })}
{#if index === 0}
<IconHome aria-label="首页" class={className} {size} />
{:else if index === 1}
<IconArticle class={className} {size} />
{/if}
{/snippet}
</Breadcrumb>
<br />
<Breadcrumb aria-label="长标题路由" routes={['首页', '当这个页面标题很长时需要省略', '详情页']} />
</div>API reference
Breadcrumb
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. | boolean | true |
| icon | Icon of each item, with the route, its index, size and class as parameters. Pass the last two to the icon. An empty result renders no icon. | TypeSnippet<[BreadcrumbIconContext]> | - |
| item | Custom title of each item, with the route and its index as parameters. It renders inline, without truncation. | TypeSnippet<[BreadcrumbRouteContext]> | - |
| maxItemCount | Number of levels above which the breadcrumb collapses. | number | 4 |
| more | Custom ellipsis area. The parameter restItems holds the collapsed items as { route, index }. | TypeSnippet<[BreadcrumbMoreContext]> | - |
| moreType | Built-in rendering of the ellipsis area: default or popover. The more snippet wins when it is provided. | BreadcrumbMoreType | "default" |
| onClick | Called on click with the route of the item ({ name } for a string route) and the native MouseEvent. It is a function prop, not the native click listener of the nav; passing it makes items without href operable with Enter as well. | BreadcrumbClick | - |
| routes | Route information as an array of route objects or strings. | TypeArray<BreadcrumbRoute | string> | [] |
| separator | Separator, either text or a snippet. | string | Snippet | "/" |
| 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 | BreadcrumbShowTooltip | { width: 150, ellipsisPos: 'end' } |
class, style, aria-label and other native attributes land on the nav root; onClick is a function prop, not the native click listener of the nav.
Breadcrumb.Item
Svelte has no Breadcrumb.Item; the data of each item is described under Route below.
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 snippet, and a custom title by the item snippet. data-* fields are passed to the item.
Accessibility
- Breadcrumb supports the
aria-labelprops 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
| 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 |