components / breadcrumbs

Breadcrumbs

Fixed-chevron path navigation with current-item emphasis and wrap-aware spacing.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Breadcrumbs represent a path through hierarchy or information structure without taking over the page chrome.
  • The DK version prioritizes current-item clarity and wrap-safe spacing.

Aliases

breadcrumb trail

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Breadcrumbs when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Breadcrumbs contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Breadcrumbs label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Breadcrumbs behind decorative copy or overloaded surface treatments.
  • Do not stretch Breadcrumbs into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Breadcrumbs when the current page belongs to a clear hierarchy and users may need to move upward.
  • Keep the labels meaningful even when the full path wraps.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Breadcrumbs when the user journey is not hierarchical.
  • Do not substitute Breadcrumbs for main navigation or step-by-step progress.

Anti-patterns

  • Using Breadcrumbs as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy breadcrumbs usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

path item

item

Each path segment in order.

path divider

separator

Fixed chevron separator between items.

current page marker

current

Current path item with stronger emphasis.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
itemsArray<{ label: string; href?: string; current?: boolean }>—Ordered breadcrumb items.
size'sm' | 'md''md'Chooses the breadcrumb size recipe.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Slots

NameDescription
defaultBreadcrumbs is data-driven in v1 and does not expose item slots.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • default: Breadcrumbs uses one structural path recipe and varies mainly by size.

Sizes

  • sm: Compact breadcrumb trail
  • md: Default breadcrumb trail

States

  • link: Navigable breadcrumb item
  • current: Current page item

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Uses ordered path semantics with clear current-item treatment.

Keyboard

  • Only linked items participate in keyboard navigation.

Screen readers

  • The current breadcrumb is distinguishable from linked ancestors.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-breadcrumbs-gap
0.5rem

item

--dk-breadcrumbs-item-fg
#16181c
--dk-breadcrumbs-item-size
0.875rem
--dk-breadcrumbs-item-block-size
44px
--dk-breadcrumbs-item-inline-padding
0.5rem
--dk-breadcrumbs-item-radius
999px

separator

--dk-breadcrumbs-separator-fg
#95989d
--dk-breadcrumbs-separator-size
0.75rem

current

--dk-breadcrumbs-current-bg
#d7e9ff
--dk-breadcrumbs-current-fg
#000f4d
--dk-breadcrumbs-current-size
0.875rem
--dk-breadcrumbs-current-inline-padding
0.625rem
--dk-breadcrumbs-current-radius
999px

Implementation notes

  • Breadcrumbs uses a fixed separator in v1 so the path remains visually consistent across presets.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: short hierarchy

A compact path back to higher-level surfaces.

Copy snippet

<Breadcrumbs items={[{ label: 'Workspace', href: '/components' }, { label: 'Release', href: '/components/card' }, { label: 'Production', current: true }]} />

Common patterns

1 example

common

Common: longer editorial path

Wrap-safe spacing matters when path labels are longer.

Copy snippet

<Breadcrumbs size="sm" items={longPathItems} />

Edge cases

1 example

edge

Edge: shallow hierarchy

Current emphasis still matters even when the path is short.

Copy snippet

<Breadcrumbs items={[{ label: 'Settings', current: true }]} />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

breadcrumbs-md

pass

size=md

  • Contrast: 89.9 Lc
  • Target: 44px
  • Layout: 267 / 220, 320