Breadcrumb handbook

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Show the current page’s hierarchy so users can see where they are and navigate to a parent page.

When to use it

Use Breadcrumb for the current page hierarchy. Use Tab to switch content at one level and Sidebar for application navigation. The page handles routing.

• Items generate the path, and the last item automatically becomes the non-interactive current page.

• Explicit children use Button as="item" and Text as="separator" to replace items; parts only configure the default generated content.

• The default navigation name follows LocaleProvider; an explicit ariaLabel takes priority. Path labels and business content remain unchanged.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Breadcrumb } from '@snowui-design-system/components';</script> <Breadcrumb	ariaLabel="SnowUI component page path"	items={[		{ label: 'Components' },		{ label: 'Navigation' },		{ label: 'Breadcrumb' }	]}/>

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Feature overview

• Default items API + explicit combination advanced API.

• The last as="item" is automatically used as the current page.

• The default Button variant can be provided to the internal Button as="item" through variant.

• Non-current items are 40% opaque by default and return to 100% on hover.

• Items share one navigation composition, so Button hover scaling is off by default. An item can explicitly set scaleOnHover={true}.

• The current page item outputs aria-current="page", which cannot be hovered, clicked, or keyboard activated.

• The separator uses 14px / 20px and black/10% by default.

Child roles

SnowUI components use as="item" / as="separator"; native elements use data-as="item" / data-as="separator".

Basic usage

<Breadcrumb>    <Button as="item" href="/dashboards">Dashboards</Button>    <Text as="separator">/</Text>    <Button as="item">Default</Button></Breadcrumb>

Unified Button variant

<Breadcrumb variant="borderless">    <Button as="item" href="/dashboards">Dashboards</Button>    <Text as="separator">/</Text>    <Button as="item" variant="outline">Custom</Button>    <Text as="separator">/</Text>    <Button as="item">Default</Button></Breadcrumb>

Breadcrumb variant supplies the default for item Buttons without their own variant. An explicit Button variant takes precedence. If Breadcrumb has no variant, each Button uses its own default.

Multi-level path

<Breadcrumb>    <Button as="item" href="/">Home</Button>    <Text as="separator">/</Text>    <Button as="item" href="/dashboards">Dashboards</Button>    <Text as="separator">/</Text>    <Button as="item" href="/dashboards/default">Default</Button></Breadcrumb>

The last item becomes the current page automatically. Even when it has href, clicking it does not navigate.

Behavior rules

1. The current page is fixed to the last as="item" / data-as="item" in Breadcrumb.

2. currentIndex is not provided, and it is not supported to specify any item as the current page.

3. The current item automatically sets aria-current="page", data-current="page", tabindex="-1".

4. The current item does not respond to Button hover, click, Enter, or Space.

5. Separator automatically sets aria-hidden="true".

6. Breadcrumb's variant only affects the default Button variant of Button as="item" and does not override the sub-level explicit variant.

7. Breadcrumb provides the default value of scaleOnHover=false for item; the explicit value of the sub-level Button takes precedence.

Layout model

Primary layout model: inline shell layout. See ../../../specs/maintainers/LayoutProtocol.md §12.4 (source reference: specs/maintainers/LayoutProtocol.md).

• Breadcrumb renders a nav root whose content hugs its intrinsic width.

• The root uses inline-flex and may wrap onto another line.

• Child Buttons keep their own inline shell layout.

• Child Text keeps its own text-flow layout.

• Breadcrumb only manages the root gap, separator style, non-current transparency and the last current state.

• Effective row and column spacing between path elements stays at least 4 CSS px, including explicit gap=0 and font/gap scaling; larger preferences are retained. The root still allows path fragments to wrap instead of forcing the entire navigation into singleLine. Button continues to own its internal single-line graphics/text layout.

Layout variable chain: