Navigation & layoutBrick 0.1.2

Breadcrumb

Breadcrumb is Brick's finished hierarchy trail. It styles Atom's named navigation landmark, ordered list, native ancestor links, current page, decorative separators, and composable Ellipsis without owning route data.

Live example

Built from the published package

Interactive

Choose with confidence

Know when Breadcrumb is the right part

Use it when

Use Breadcrumb on a page whose ancestors help people understand where they are and move upward through a site or application hierarchy. It is especially useful on deep pages reached from search, notifications, or external links.

Choose another path when

Use Nav List for peer destinations rather than ancestry.
Use Tabs for views of the same context.
Use Pagination for numbered results.
Do not use Breadcrumb as browser history or a linear step indicator.
Omit it when a shallow site or nearby navigation already makes location clear.

Breadcrumb does not provide route objects, automatic collapse, menus, navigation callbacks, structured search metadata, or analytics.

Installation and imports

tsx

import { Breadcrumb } from "@flowstack-ui/brick";
// or: import { Breadcrumb } from "@flowstack-ui/brick/breadcrumb";
import "@flowstack-ui/brick/styles.css";

The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:

tsx

import "@flowstack-ui/brick/styles/core.css"; // once at the application root
import "@flowstack-ui/brick/styles/breadcrumb.css";

Add the modular stylesheet for every other Brick component the route renders. Do not combine modular styles with styles.css or tokens.css.

Brick requires its exact public Atom dependency and React 18 or newer.

Quick start

tsx

<Breadcrumb.Root>
  <Breadcrumb.List>
    <Breadcrumb.Item>
      <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
    </Breadcrumb.Item>
    <Breadcrumb.Separator />
    <Breadcrumb.Item>
      <Breadcrumb.Link href="/projects">Projects</Breadcrumb.Link>
    </Breadcrumb.Item>
    <Breadcrumb.Separator />
    <Breadcrumb.Item>
      <Breadcrumb.Page>Quarterly report</Breadcrumb.Page>
    </Breadcrumb.Item>
  </Breadcrumb.List>
</Breadcrumb.Root>

Visual recipes and states

md is the default body-size trail; sm and lg change typography, spacing, and separator metrics together.
plain keeps ancestor links undecorated at rest and underlines them on hover, focus-visible, and active interaction.
underline keeps a visible underline at rest.
Ancestors use secondary neutral text. The current Page uses primary text and medium weight.
Separator and Ellipsis use secondary text color.
Root has no surface, border, elevation, or width recipe.
Hover, active, focus, and current states never change geometry.
Dark appearance and forced colors retain link, current-page, separator, and focus distinctions. Breadcrumb has no motion.

Examples

Underlined compact trail

tsx

<Breadcrumb.Root size="sm" variant="underline">
  <Breadcrumb.List>
    <Breadcrumb.Item><Breadcrumb.Link href="/">Home</Breadcrumb.Link></Breadcrumb.Item>
    <Breadcrumb.Separator />
    <Breadcrumb.Item><Breadcrumb.Page>Documentation</Breadcrumb.Page></Breadcrumb.Item>
  </Breadcrumb.List>
</Breadcrumb.Root>

Custom separator

tsx

<Breadcrumb.Separator>
  <ChevronRightIcon aria-hidden="true" />
</Breadcrumb.Separator>

Expanded manual collapse

tsx

{expanded ? (
  <Breadcrumb.Item>
    <Breadcrumb.Link href="/projects">Projects</Breadcrumb.Link>
  </Breadcrumb.Item>
) : (
  <Breadcrumb.Item>
    <Breadcrumb.Ellipsis asChild>
      <button type="button" aria-label="Show collapsed pages" onClick={() => setExpanded(true)}>…</button>
    </Breadcrumb.Ellipsis>
  </Breadcrumb.Item>
)}

Public contract

API

Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.

Exports

Breadcrumb, BreadcrumbRoot, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis, BreadcrumbRootProps, BreadcrumbListProps, BreadcrumbItemProps, BreadcrumbLinkProps, BreadcrumbPageProps, BreadcrumbSeparatorProps, BreadcrumbEllipsisProps, BreadcrumbSize, and BreadcrumbVariant are available from root and subpath imports.

Root recipes

Prop	Values	Default
`size`	`sm`, `md`, `lg`	`md`
`variant`	`plain`, `underline`	`plain`
`ariaLabel`	`string`	`"Breadcrumb"`

Root accepts native nav props plus Atom render and asChild. Recipe props become data-size and data-variant and do not leak as native attributes.

Parts

List accepts native ordered-list props.
Item and Separator accept native list-item props.
Link accepts native anchor props such as href, target, rel, and download.
Page accepts native span props and always supplies aria-current="page".
Separator defaults to / and always supplies role="presentation" and aria-hidden="true".
Ellipsis defaults to … and may compose an interactive final host.
Every part accepts className, style, custom data attributes, render, asChild, and its matching ref.

There are no tone, shape, disabled, loading, selection, collapse, or data-array props.

Shared responsibility

Accessibility

Root supplies a named navigation landmark; use a more specific ariaLabel when a page contains multiple breadcrumb trails.
Keep Items in ancestor-to-current order and render exactly one Page.
Use complete, destination-specific link text and the same current-page words as the visible page title when practical.
Separator is decorative and hidden by Atom. Do not move meaningful content into it.
Native Links retain normal Tab order, Enter activation, modifier keys, context menus, target, and download behavior. Breadcrumb adds no arrow-key or roving-focus model.
Interactive Ellipsis must compose a real button/menu trigger and have a name such as “Show collapsed pages.” Static Ellipsis is not interactive.
The final hierarchy and routing policy must be tested in the consuming page.

Responsive behavior

The List wraps by default and remains bounded by Root. Items stay content-sized and never stretch to fill a row. Long and localized labels may wrap and break long tokens rather than clip or create page-level horizontal scrolling.

At narrow widths, 200% text size, 400% zoom, or increased text spacing, keep the full hierarchy when it remains useful. If product policy requires fewer items, explicitly compose Ellipsis and a disclosure/menu rather than relying on visual clipping.

Stable visual contract

Styling and tokens

Customization

Choose Root recipes first, then customize semantic tokens or component variables in a scoped class.

tsx

<Breadcrumb.Root
  className="project-path"
  style={{
    "--brick-breadcrumb-foreground": "var(--brick-color-accent-text)",
    "--brick-breadcrumb-separator-size": "1.125em",
  } as React.CSSProperties}
>
  {/* complete List anatomy */}
</Breadcrumb.Root>

Customized colors must remain readable in every supported appearance. Do not remove the focus ring or hide link affordance solely through color.

Tokens and CSS hooks

Stable classes:

.brick-breadcrumb
.brick-breadcrumb-list
.brick-breadcrumb-item
.brick-breadcrumb-link
.brick-breadcrumb-page
.brick-breadcrumb-separator
.brick-breadcrumb-ellipsis

Stable Root data hooks are data-size and data-variant; every part retains its data-slot.

Public variables:

--brick-breadcrumb-foreground
--brick-breadcrumb-foreground-hover
--brick-breadcrumb-foreground-active
--brick-breadcrumb-current-foreground
--brick-breadcrumb-separator-foreground
--brick-breadcrumb-ellipsis-foreground
--brick-breadcrumb-ellipsis-hover-background
--brick-breadcrumb-focus-ring
--brick-breadcrumb-list-gap
--brick-breadcrumb-item-gap
--brick-breadcrumb-target-size
--brick-breadcrumb-font-family
--brick-breadcrumb-font-size
--brick-breadcrumb-font-weight
--brick-breadcrumb-line-height
--brick-breadcrumb-letter-spacing
--brick-breadcrumb-current-font-weight
--brick-breadcrumb-decoration-thickness
--brick-breadcrumb-decoration-offset
--brick-breadcrumb-separator-size

Advanced reference

Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.

Maintainer resources

Tests, playground evidence, source notes, and release history remain available without crowding the plug-and-play guide.

Source docs Changelog Playground