Breadcrumb

A trail of links to the pages above this one. CSS only. CSS only

Choosing between components

A breadcrumb says where the current page sits in a hierarchy. For moving between siblings at the same level use Tabs, and for a list of pages in a sequence use Pagination.

Markup you author

Give the <nav> an aria-label — a page can hold several landmarks of the same type, and an unnamed one is indistinguishable from the rest. Author the final crumb as a <span data-ui-part="current" aria-current="page"> rather than a link: a link to the page you are already on goes nowhere. Author nothing between the crumbs; the separator is drawn.

Breadcrumb

Copy this markup

<nav class="ui-breadcrumb" aria-label="Breadcrumb">
  <ol>
    <li data-ui-part="item"><a data-ui-part="link" href="/docs/">Documentation</a></li>
    <li data-ui-part="item"><a data-ui-part="link" href="/docs/components/">Components</a></li>
    <li data-ui-part="item"><span data-ui-part="current" aria-current="page">Breadcrumb</span></li>
  </ol>
</nav>

Install

Styles and registration

import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/breadcrumb.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/breadcrumb.css'

Anatomy

Parts are authored in your own markup and identified by the selector below, so your CSS can target the same anatomy without loading Timeless styles. Required parts must be present for the component to work. Private data-ui-internal-* hooks are written by the runtime and must never be authored.

Part	Required	Selector	Purpose
item	No	[data-ui-part~='item']	One crumb. Use <li>; the separator is drawn before every crumb but the first, so nothing is authored between them.
link	No	[data-ui-part~='link']	The link inside a crumb. Use <a href>.
current	No	[data-ui-part~='current']	The final crumb, which names the page you are already on. Author it as a <span> rather than a link — a link to here goes nowhere — and put aria-current="page" on it.

Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes are presence-based: author the attribute with no value, or omit it.

Attribute	Values	Default	Description
data-ui-separator	chevron · slash	chevron	Which glyph is drawn between crumbs. Both are generated content rather than markup, so neither reaches the accessibility tree and neither is yours to author. For any other glyph, set --ui-breadcrumb-separator instead of asking for a new value here.
data-ui-density	compact · normal	normal	Gap between a crumb and its separator.

State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through the selectors below rather than adding your own state classes.

State	Source	How to express it
current	aria	Author aria-current="page" on the final crumb. Timeless never writes it: which page you are on is not something a stylesheet can know.

Styling

Root identity: ui-breadcrumb. Required stylesheets: tokens.css, core/breadcrumb.css, themes/atmosphere/tokens.css, themes/atmosphere/breadcrumb.css.

Set these custom properties to restyle the component:

Custom property	Controls
--ui-breadcrumb-gap	Gap between a crumb and its separator.
--ui-breadcrumb-separator	The separator glyph, as a CSS string. Comes from data-ui-separator; set it directly for a glyph the attribute does not offer. Keep the / "" alternative text if you redeclare content yourself, or the glyph starts being announced.

Design tokens this component reads (9)

These are global Atmosphere tokens. Change them once at the theme level rather than per component.

--ui-duration-fast · --ui-ease-standard · --ui-fg · --ui-fg-muted · --ui-fg-subtle · --ui-focus · --ui-radius-xs · --ui-space-1 · --ui-space-3

Accessibility

Keep the native elements, roles, and relationships shown in the example. Timeless adds only the state and keyboard coordination the platform does not already provide, and it never supplies your accessible names — those depend on your content.

Follows the Breadcrumb pattern from the ARIA Authoring Practices Guide.

No keyboard behavior of its own, and the APG says so too: a breadcrumb is links in a labelled landmark, and Tab is the traversal. Author <nav> with an aria-label, an <ol> inside it, and the final crumb as an unlinked <span aria-current="page">. The separator is a ::before pseudo-element with empty alternative text, so it is drawn but never announced — which is why there is no separator part to author and no aria-hidden to remember.

Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

More examples

Open Breadcrumb in StoryLite for variants, controls, and manual testing.