Skip to main content

Breadcrumb

A fully accessible headless breadcrumb component for displaying hierarchical navigation paths with complete keyboard support and screen reader compatibility.

Live Demo​

This example shows a minimal breadcrumb trail with one navigable step and one current-page indicator.

Features​

  • ✅ Automatic position detection for styling hooks
  • ✅ External link security (rel="noopener noreferrer")
  • ✅ Polymorphic components with 'as' prop support
  • ✅ Navigation integration with custom routing
  • ✅ Individual and global disabled states
  • ✅ Render props support for conditional rendering based on item state
  • ✅ Full support for icons and custom content in links

Import​

import { Breadcrumb } from '@turkish-technology/spar';

Anatomy​

The Breadcrumb component is built as a compound component with multiple parts:

Parts
RootNavigation landmark container
ListOrdered list with position calculation
ItemIndividual list item wrapper
LinkNavigational link element
PageCurrent page indicator
SeparatorVisual separator element

Structure​

<Breadcrumb.Root>
<Breadcrumb.List>
<Breadcrumb.Item>
<Breadcrumb.Link />
</Breadcrumb.Item>
<Breadcrumb.Separator />
<Breadcrumb.Item>
<Breadcrumb.Page />
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>

Data Flow:

  • Breadcrumb.Root provides navigation context and manages shared state
  • Breadcrumb.List calculates position data (first, middle, last) for items
  • Breadcrumb.Item receives position information for styling hooks
  • Breadcrumb.Link handles navigation and routing integration
  • Breadcrumb.Page marks the current page with proper ARIA attributes
  • Breadcrumb.Separator provides visual separation (hidden from screen readers)

Code Examples​

Basic Navigation​

function SimpleBreadcrumb() {
return (
<Breadcrumb.Root>
<Breadcrumb.List>
<Breadcrumb.Item>
<Breadcrumb.Link href="/">Home</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>/</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Link href="/docs">Documentation</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>/</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Page>Breadcrumb</Breadcrumb.Page>
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>
);
}

Router Integration​

import { useRouter } from 'next/router';

function RouterBreadcrumb() {
const router = useRouter();

const handleNavigate = (href: string, event: PressEvent) => {
event.preventDefault();
router.push(href);
};

return (
<Breadcrumb.Root onNavigate={handleNavigate} aria-label="Site navigation">
<Breadcrumb.List>
<Breadcrumb.Item>
<Breadcrumb.Link href="/">Dashboard</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>→</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Link href="/users">Users</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>→</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Page>Profile Settings</Breadcrumb.Page>
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>
);
}
function ExternalLinksBreadcrumb() {
return (
<Breadcrumb.Root>
<Breadcrumb.List>
<Breadcrumb.Item>
<Breadcrumb.Link href="/">Internal</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>|</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Link
href="https://external-docs.example.com"
isExternal={true}
>
External Docs
</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>|</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Page>Current Page</Breadcrumb.Page>
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>
);
}

Disabled States​

function DisabledBreadcrumb() {
const [isNavigationDisabled, setIsNavigationDisabled] = React.useState(false);

return (
<div>
<button onClick={() => setIsNavigationDisabled(!isNavigationDisabled)}>
Toggle Navigation: {isNavigationDisabled ? 'Disabled' : 'Enabled'}
</button>

<Breadcrumb.Root disabled={isNavigationDisabled}>
<Breadcrumb.List>
<Breadcrumb.Item>
<Breadcrumb.Link href="/">Home</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>›</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Link href="/products" disabled={true}>
Products (Individual Disabled)
</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>›</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Page>Current</Breadcrumb.Page>
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>
</div>
);
}

With Icons​

function IconBreadcrumb() {
// Simple SVG icon components
const HomeIcon = () => (
<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
<path d="M8 1l7 7-1.5 1.5L12 8v6H9V9H7v5H4V8L2.5 9.5 1 8z" />
</svg>
);

const FolderIcon = () => (
<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
<path d="M7 3l2 2h5v8H2V3h5z" />
</svg>
);

const FileIcon = () => (
<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
<path d="M9 1H3v14h10V5L9 1z" />
</svg>
);

return (
<Breadcrumb.Root>
<Breadcrumb.List>
<Breadcrumb.Item>
<Breadcrumb.Link href="/">
<HomeIcon />
<span>Home</span>
</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>/</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Link href="/documents">
<FolderIcon />
<span>Documents</span>
</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>/</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Page>
<FileIcon />
<span>Report.pdf</span>
</Breadcrumb.Page>
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>
);
}

Custom Event Handling​

function CustomEventBreadcrumb() {
const handleCustomPress = (event: PressEvent) => {
console.log('Custom action triggered:', event.type);
// Custom logic here - overrides default navigation
};

return (
<Breadcrumb.Root>
<Breadcrumb.List>
<Breadcrumb.Item>
<Breadcrumb.Link href="/" onPress={handleCustomPress}>
Custom Action Link
</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator>•</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Page>Current</Breadcrumb.Page>
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>
);
}

Render Props​

Breadcrumb.Item accepts a render function as children, providing access to position, isCurrent, and isDisabled state. This is useful for conditionally rendering custom components like Next.js Link or React Router Link based on item state.

import NextLink from 'next/link';

function RenderPropsBreadcrumb() {
return (
<Breadcrumb.Root>
<Breadcrumb.List>
<Breadcrumb.Item>
{({ isCurrent, position, isDisabled }) =>
isCurrent ? (
<Breadcrumb.Page>{`Current (${position})`}</Breadcrumb.Page>
) : (
<Breadcrumb.Link as={NextLink} href="/home" disabled={isDisabled}>
Home
</Breadcrumb.Link>
)
}
</Breadcrumb.Item>
<Breadcrumb.Separator>/</Breadcrumb.Separator>
<Breadcrumb.Item>
{({ isCurrent }) =>
isCurrent ? (
<Breadcrumb.Page>Settings</Breadcrumb.Page>
) : (
<Breadcrumb.Link href="/settings">Settings</Breadcrumb.Link>
)
}
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>
);
}

The render function receives the following properties:

PropertyTypeDescription
position'first' | 'middle' | 'last'Position of the item in the breadcrumb trail
isCurrentbooleanWhether this item is the current (last) page
isDisabledbooleanWhether breadcrumb navigation is disabled from root

Polymorphic Usage​

import { Link } from 'react-router-dom';

function PolymorphicBreadcrumb() {
return (
<Breadcrumb.Root as="section">
<Breadcrumb.List as="ul">
<Breadcrumb.Item as="div">
<Breadcrumb.Link as={Link} to="/home">
React Router Link
</Breadcrumb.Link>
</Breadcrumb.Item>
<Breadcrumb.Separator as="span">–</Breadcrumb.Separator>
<Breadcrumb.Item>
<Breadcrumb.Page as="h1">Page Title</Breadcrumb.Page>
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>
);
}

API Reference​

Navigation landmark container that provides context and manages shared state for all breadcrumb components. Breadcrumb and Breadcrumb.Root are the same component - the difference is only import/notation style.

Props

NameTypeDefaultDescription
childrenReact.ReactNode-Breadcrumb content
as?React.ElementType'nav'Polymorphic element type
aria-label?string'Breadcrumb'Accessible name for navigation landmark
onNavigate?NavigationHandlerundefinedNavigation event handler for routing integration
disabled?booleanfalseDisable all breadcrumb navigation

Events

NameParametersDescriptionWhen Triggered
onNavigate(href: string, event: PressEvent)Navigation handler called when links are activatedLink click or keyboard activation

HTML Attributes

AttributeValuePurpose
aria-labelstringValue from aria-label prop
aria-disabled"true"Present when disabled is true
data-disabled""Present when disabled is true

Ordered list container that provides semantic structure and automatically calculates position data for child items.

Props

NameTypeDefaultDescription
childrenReact.ReactNode-List items content
as?React.ElementType'ol'Polymorphic element type

Events

NameParametersDescriptionWhen Triggered
(No specific events)-Inherits standard HTML eventsStandard DOM interactions

List item wrapper that receives position and current state from parent Breadcrumb.List for styling hooks and accessibility.

Props

NameTypeDefaultDescription
childrenReact.ReactNode | ((props: BreadcrumbItemRenderProps) => React.ReactNode)-Item content or render function receiving item state
as?React.ElementType'li'Polymorphic element type

position and isCurrent are not props: each item registers with its Breadcrumb.List and derives them automatically from DOM order. Read them through the render-function children or the data-position / data-current attributes.

Events

NameParametersDescriptionWhen Triggered
(No specific events)-Inherits standard HTML eventsStandard DOM interactions

HTML Attributes

AttributeValuePurpose
data-position"first" | "middle" | "last"Indicates position in breadcrumb
data-current""Present when this is the current page

Interactive link component with accessibility features, routing integration, and security for external links.

Props

NameTypeDefaultDescription
childrenReact.ReactNode-Link text content
as?React.ElementType'a'Polymorphic element type
href?stringundefinedLink destination
disabled?booleanfalseDisable this specific link
isExternal?booleanfalseIndicates external link (adds security attributes)
onPress?(event: PressEvent) => voidundefinedPress handler for click/Enter/Space; replaces onNavigate
target?stringundefinedLink target (auto-set to '_blank' for external links)
rel?stringundefinedLink relationship (auto-set to 'noopener noreferrer' for external)

Events

NameParametersDescriptionWhen Triggered
onPress(event: PressEvent)Custom press handler that replaces onNavigateClick, Enter, or Space key, after onClick/onKeyDown and unless they called preventDefault(). Not called while disabled
onClick(event: React.MouseEvent)Standard click handler, runs firstEvery click on an enabled link; preventDefault() skips onPress/onNavigate. Not called while disabled
onKeyDown(event: React.KeyboardEvent)Standard keyboard handler, runs firstEvery key on an enabled link; on Enter/Space preventDefault() skips onPress/onNavigate. While disabled, Enter/Space are blocked and every other key still arrives

HTML Attributes

AttributeValuePurpose
aria-disabled"true"Present when link is disabled
data-disabled""Present when link is disabled
data-external""Present when link is external
tabIndex-1Set to -1 when disabled

Non-interactive current page indicator with proper semantic marking for screen readers.

Props

NameTypeDefaultDescription
childrenReact.ReactNode-Current page name
as?React.ElementType'span'Polymorphic element type

Events

NameParametersDescriptionWhen Triggered
(No specific events)-Inherits standard HTML eventsStandard DOM interactions

HTML Attributes

AttributeValuePurpose
aria-current"page"Always present; marks the current page
data-current""Always present on the current page element

Visual separator between breadcrumb items, hidden from screen readers to prevent verbose announcements.

Props

NameTypeDefaultDescription
children?React.ReactNodeundefinedCustom separator content
as?React.ElementType'li'Polymorphic element type
aria-hidden?booleantrueHide from screen readers

Events

NameParametersDescriptionWhen Triggered
(No specific events)-Inherits standard HTML eventsStandard DOM interactions

Keyboard Interactions​

Complete keyboard behavior for the entire breadcrumb component:

KeyActionContextNotes
TabNavigate forwardAlwaysMoves focus to next focusable breadcrumb link
Shift + TabNavigate backwardAlwaysMoves focus to previous focusable breadcrumb link
EnterActivate linkFocused linkTriggers navigation or onPress handler
SpaceActivate linkFocused linkAlternative activation method for links
EscapeNo actionBreadcrumbBreadcrumbs don't trap focus or need escape behavior
Arrow KeysNo actionBreadcrumbNot applicable - breadcrumbs use standard tab navigation
HomeNo actionBreadcrumbNot applicable - use Tab to navigate to first link
EndNo actionBreadcrumbNot applicable - use Tab to navigate to last link

Note: Disabled links are automatically skipped in the tab order and do not respond to keyboard activation. The current page element (Breadcrumb.Page) is not focusable as it represents static content.