lab components / Navigation

Breadcrumbs

Show users their path and allow quick backtracking to higher-level pages.

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { Breadcrumbs } from "@siteimprove/fancylab";

#Examples

Breadcrumbs are a secondary navigation aid, showing users their current location within an application and enabling quick navigation back to higher-level pages.

The standard breadcrumb displays a clickable path of the user's current location. Each segment represents a level in the hierarchy, separated by the visual delimiter "/". The final segment (current page) is rendered as text, and therefore the last item in the items array should not have a url or onClick prop or the value of those should be null.

Best practices:

Use for applications with multi-step processes where users need to track progress.
Start with the highest-level parent page and move deeper into the information architecture as the breadcrumb trail progresses.
Limit breadcrumbs to a maximum of 6 items for optimal usability. (See guideline below).

Use cases:

Use for applications with multi-step processes where users need to track progress.

CodeHTML output

const items = [
	{ title: "Siteimprove", url: "https://siteimprove.com/" },
	{ title: "Github", url: "https://github.com/" },
	{ title: "Wikipedia" },
];

return <Breadcrumbs items={items} aria-label="Breadcrumbs" />;

This type visually represents the path but without clickable links or onClick handlers. It's used to show the user's location. In the example below, the url props have the value null, but the props can also be omitted.

Use cases:

Use for read-only views (e.g., search results) where navigation isn't necessary.
Use when the hierarchy is simple and easily understood without clicking.

CodeHTML output

const items = [
	{ title: "Siteimprove", url: null },
	{ title: "Github", url: null },
	{ title: "Not Navigable", url: null },
];

return <Breadcrumbs items={items} aria-label="Breadcrumbs - non-navigable current page" />;

This variation allows custom actions (e.g., filtering, triggering functions) when a breadcrumb segment is clicked.

Best practices:

Page content-specific actions tied to the breadcrumb's context

CodeHTML output

const items = [
	{ title: "Products", url: "#", onClick: () => alert("Products") },
	{ title: "Documentation", url: "#", onClick: () => alert("Documentation") },
	{ title: "Contact us" },
];

return <Breadcrumbs items={items} aria-label="Breadcrumbs - custom onclick event" />;

Property	Description	Defined	Value
itemsRequired	`object[]`	YesNo
aria-labelRequired	`string`	YesNo
noPaddingOptional	`boolean`If true, the breadcrumb will not have padding	YesNo	truefalse

There are multiple navigation levels and a clear hierarchy.
Users need to understand their location.
Users may want to quickly return to higher-level pages.

#Placement

Breadcrumbs are typically used in the following places:

Above the page header (most common).
Above the main content.

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your Breadcrumbs to existing components for visual consistency.
Delimiter: Use a clear and visually distinct delimiter between segments e.g. ("/").
Typography: Use a legible font size (e.g $font-size--medium) and style (e.g $font-family--default and $font-weight--normal) that contrasts with the background.
Color: Use a color (by default, is using $color--blue) that contrasts with the background and does not clash with other elements on the page.
Breadcrumb maximum items: Limit Breadcrumbs to a maximum of 6 items for optimal usability. If there is not enough space to fully display the breadcrumbs, automatically collapse them, showing the first and last items with an ellipsis ("...") in between. The ellipsis should be clickable to reveal all items. Examples:
- Original: Item 1 / Item 2 / Item 3 / Item 4 / Item 5 / Item 6
- Collapsed: Item 1 / ... / Item 7

#Do not use when

Single-level pages.
When the user's location is always obvious (e.g., Side Navigation’s item).
When breadcrumbs would take up valuable space without providing a clear benefit.