---
name: breadcrumb-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Breadcrumb for
page hierarchy navigation with Link/NextLink adapters, current page state,
separators, ellipsis, icons, size, and underline variant.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux framework-consumer-integration app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: ""
contributor_sources: "libs/ui/src/molecules/breadcrumb.tsx libs/ui/src/tokens/components/molecules/_breadcrumb.css libs/ui/stories/molecules/breadcrumb.stories.tsx libs/ui/src/molecules/breadcrumb.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Breadcrumb Usage
Use Breadcrumb for location hierarchy, not for primary navigation tabs.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Breadcrumb`.
**Use it when**
- Pages three or more levels deep in a hierarchy (catalog → category → product; admin → section → record).
- Record editors and detail pages, so users can return to the list they came from.
- Storefront category and product pages, where it also helps SEO.
**Use something else when**
| Need | Use instead |
| --- | --- |
| Switching peer views | Tabs |
| Progress through a task | Steps |
| Primary site navigation | Header / Sidebar + VerticalNavigation |
| Browser-history back | a `Back to list` Button in the page header |
**Do**
- Start at the root users recognise (`Home` or the section), end with the current page as plain text (not a link).
- Mirror the information architecture, not the click history.
- Truncate the middle on small screens, never the current page.
- Use the same labels as the navigation and page titles.
**Don't**
- Link the current page to itself.
- Use breadcrumbs on top-level pages where they only contain `Home`.
- Replace the page title with the last breadcrumb — keep both.
**Copy and states**
- Labels are page names in sentence case; separators come from the component, never typed characters.
**Behaviour (from the UX spec)**
- The trail follows the hierarchy, not the click history: the same record shows the same ancestors however the user reached it.
- Collapsed levels must stay reachable. `Breadcrumb.Ellipsis` is currently decorative (`aria-hidden`), so keep `maxItems` generous enough that nothing the user needs is hidden.
- Pass a localised `aria-label` on the root (the default is `breadcrumb`).
**Figma → code**
| Figma | Code |
| --- | --- |
| `size=sm…lg` | same prop |
| — | `appearance="plain" \| "underline"` (not in Figma) |
| ellipsis glyph / hidden levels | `Breadcrumb.Ellipsis`, `maxItems` on `BreadcrumbTemplate` |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Breadcrumb → UX guidelines*.
## Setup
```tsx
import NextLink from "next/link"
import { Breadcrumb } from "@techsio/ui-kit/molecules/breadcrumb"
HomeProducts
```
Supported props:
```text
Breadcrumb: size sm | md | lg, variant plain | underline
Link: as, href, external, framework link props
CurrentLink: aria-current page
Separator/Ellipsis/Icon: token icon defaults with icon override props
```
## Core Patterns
### Use CurrentLink for the current page
The last breadcrumb should be `Breadcrumb.CurrentLink`, not a clickable link to
the same page.
### Use framework link adapters
In Next apps, pass `as={NextLink}` to `Breadcrumb.Link` instead of wrapping or
restyling anchors.
### Keep demos local without changing production links
Breadcrumb links are real anchors with real destinations. The molecule and
BreadcrumbTemplate Storybook stories prevent default link activation in their
demo decorator and log the destination; this also covers keyboard activation
and destinations edited in Controls. That suppression is documentation-only.
Do not copy it into application navigation or replace real routes with `#`.
Use BreadcrumbTemplate when an array of page data is enough; use the compound
Breadcrumb molecule when individual slots need custom content or styling.
The template's `maxItems` counts visible page items, not the decorative
ellipsis: `0` shows all, `1` shows the last, and larger limits preserve the root
and the trailing pages. Keep the current page in that visible trailing segment.
### Use separators and ellipsis components
Let `Breadcrumb.Separator` and `Breadcrumb.Ellipsis` supply token icons and
ARIA behavior.
## Common Mistakes
### HIGH Native breadcrumb markup
Wrong:
```tsx
```
Correct:
```tsx
{/* items */}
```
Source: libs/ui/src/molecules/breadcrumb.tsx
### HIGH Missing framework adapter
Wrong:
```tsx
Products
```
Correct in Next:
```tsx
Products
```
Source: libs/ui/src/atoms/link.tsx
### MEDIUM Inline separator or text styling
Wrong:
```tsx
/
```
Correct:
```tsx
```
Source: libs/ui/src/tokens/components/molecules/_breadcrumb.css
## Validation Commands
```sh
rg -P -n "