Breadcrumbs

01Preview

Change the controls to try every supported combination. The preview renders the real component and the code updates with it. Links are live but don't leave the page.

import { Breadcrumb, BreadcrumbItem } from '@nuton/ui'
import { RiHomeSmile2Line } from '@remixicon/react'

<Breadcrumb label="Playground location">
  <BreadcrumbItem href="/" icon={<RiHomeSmile2Line />}>Home</BreadcrumbItem>
  <BreadcrumbItem href="/spaces/">Spaces</BreadcrumbItem>
  <BreadcrumbItem href="/spaces/biology-101/">Biology 101</BreadcrumbItem>
  <BreadcrumbItem href="/spaces/biology-101/lessons/">Lessons</BreadcrumbItem>
  <BreadcrumbItem current>Cell structure</BreadcrumbItem>
</Breadcrumb>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. @remixicon/react supplies the arrow divider and any item icons (D1). Breadcrumb has no client state, so it renders in server components.

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

03Usage

import { Breadcrumb, BreadcrumbItem } from '@nuton/ui'

export function LessonBreadcrumb() {
  return (
    <Breadcrumb>
      <BreadcrumbItem href="/spaces/">Spaces</BreadcrumbItem>
      <BreadcrumbItem href="/spaces/biology-101/">Biology 101</BreadcrumbItem>
      <BreadcrumbItem current>Cell structure</BreadcrumbItem>
    </Breadcrumb>
  )
}

• List items from the top of the hierarchy down. The last item is the current page: set current and leave out href.
• Breadcrumb renders a <nav> landmark named “Breadcrumb”. Translate label in other languages, and give each breadcrumb a different label when a page has more than one.
• Use the page titles people see in each page's heading, in sentence case: “Biology 101”, “Cell structure”.
• Pass your router's link component through as so navigation stays client-side.

This site's own header already has a landmark named “Breadcrumb”, so every example on this page passes a different label, which is the second rule above in practice.

04Variants and sizes

Breadcrumbs have one size. The divider is set once on Breadcrumb; each item can show text, an icon, or both.

Dividers

<Breadcrumb label="Arrow divider">…</Breadcrumb>                    // default
<Breadcrumb label="Slash divider" separator="slash">…</Breadcrumb>
<Breadcrumb label="Dot divider" separator="dot">…</Breadcrumb>

// Each one contains:
<BreadcrumbItem href="/spaces/">Spaces</BreadcrumbItem>
<BreadcrumbItem href="/spaces/biology-101/">Biology 101</BreadcrumbItem>
<BreadcrumbItem current>Cell structure</BreadcrumbItem>

Arrow is Remix arrow-right-s-line in Icon/Disabled-300, mirrored in right-to-left pages. Slash (“/”) and dot (“•”) are Label/Small text in Text/Disabled-500. You can pass any node as a custom divider, but it isn't in Figma, so prefer the three presets. Dividers are always hidden from screen readers. Use one divider style across a product.

Item content

Figma's Icon and Text options. An icon-only item has no visible label, so it needs aria-label. Figma's default icon is home-smile-2-line, for the first item.

<Breadcrumb label="Icon and text">
  <BreadcrumbItem href="/" icon={<RiHomeSmile2Line />}>Home</BreadcrumbItem>
  <BreadcrumbItem href="/spaces/">Spaces</BreadcrumbItem>
  <BreadcrumbItem current>Biology 101</BreadcrumbItem>
</Breadcrumb>

<Breadcrumb label="Icon only">
  <BreadcrumbItem href="/" icon={<RiHomeSmile2Line />} aria-label="Home" />
  <BreadcrumbItem href="/spaces/">Spaces</BreadcrumbItem>
  <BreadcrumbItem current>Biology 101</BreadcrumbItem>
</Breadcrumb>

<Breadcrumb label="Text only">
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/spaces/">Spaces</BreadcrumbItem>
  <BreadcrumbItem current>Biology 101</BreadcrumbItem>
</Breadcrumb>

Sizes

Sizes come from the component CSS, which follows Figma's geometry. Figma's text-only item has an 8px gap, which has no visible effect, so code uses 6 throughout.

Long trails

On narrow screens the trail wraps onto more lines instead of scrolling the page. A single label longer than the line is cut short with an ellipsis. This preview limits the width so the trail wraps.

<Breadcrumb label="Long trail">
  <BreadcrumbItem href="/" icon={<RiHomeSmile2Line />} aria-label="Home" />
  <BreadcrumbItem href="/spaces/">Spaces</BreadcrumbItem>
  <BreadcrumbItem href="/spaces/biology-101/">Biology 101</BreadcrumbItem>
  <BreadcrumbItem href="/spaces/biology-101/lessons/">Lessons</BreadcrumbItem>
  <BreadcrumbItem current>Photosynthesis and cellular respiration</BreadcrumbItem>
</Breadcrumb>

05States and interactions

There is no disabled state: a page people can't open shouldn't be in the trail.

State tokens

Set on .nu-breadcrumb. Override them on a wrapper only for a documented exception.

06Composition examples

Lesson page header

The breadcrumb sits above the page title and the page's own tabs. It shows where the lesson lives; the tabs switch views inside it.

<Breadcrumb label="Lesson location">
  <BreadcrumbItem href="/" icon={<RiHomeSmile2Line />} aria-label="Home" />
  <BreadcrumbItem href="/spaces/biology-101/">Biology 101</BreadcrumbItem>
  <BreadcrumbItem current>Cell structure</BreadcrumbItem>
</Breadcrumb>
<h1>Cell structure</h1>
<Tabs defaultValue="lesson">
  <TabsList aria-label="Cell structure">
    <TabsTrigger value="lesson">Lesson</TabsTrigger>
    <TabsTrigger value="notes">Notes</TabsTrigger>
  </TabsList>
  <TabsContent value="lesson"><p>Cells are the basic unit of life.</p></TabsContent>
  <TabsContent value="notes"><p>You haven't added any notes yet.</p></TabsContent>
</Tabs>

The preview stands in a paragraph for the <h1>, because this page already has one.

Router links

Pass your router's link through as. It receives href, className, aria-current and the other props, so styling and semantics are unchanged.

import Link from 'next/link'
import { Breadcrumb, BreadcrumbItem } from '@nuton/ui'

<Breadcrumb label="Student location">
  <BreadcrumbItem as={Link} href="/spaces/biology-101/">Biology 101</BreadcrumbItem>
  <BreadcrumbItem as={Link} href="/spaces/biology-101/students/">Students</BreadcrumbItem>
  <BreadcrumbItem current>Progress report</BreadcrumbItem>
</Breadcrumb>

Built from route data

Most apps build the trail from the route. Give each item a stable key, and mark only the last one as current.

const trail = [
  { href: '/spaces/', title: 'Spaces' },
  { href: '/spaces/biology-101/', title: 'Biology 101' },
  { href: '/spaces/biology-101/resources/', title: 'Resources' },
]

<Breadcrumb label="Resource location">
  {trail.map((page, i) =>
    i === trail.length - 1
      ? <BreadcrumbItem key={page.href} current>{page.title}</BreadcrumbItem>
      : <BreadcrumbItem key={page.href} href={page.href}>{page.title}</BreadcrumbItem>,
  )}
</Breadcrumb>

07API reference

Props

Breadcrumb: the navigation landmark and its list.

BreadcrumbItem: one page in the trail.

Types are exported as BreadcrumbProps, BreadcrumbItemProps and BreadcrumbSeparator.

Styling hooks

Breadcrumb renders nav.nu-breadcrumb with data-separator (arrow, slash, dot or custom), an ol.nu-breadcrumb__list, and li.nu-breadcrumb__separator between items. Each item is li.nu-breadcrumb__item around .nu-breadcrumb__link, with data-current and data-icon-only. Use props rather than styling these; the --nu-breadcrumb-* tokens (see State tokens) are the supported override points.

Accessibility

You must: mark the last item current and leave out its href; give icon-only items an aria-label; give each breadcrumb on a page a unique, translated label.

Figma mapping

Nodes: 292:18369 (page), 292:18404 (group), 292:18382 (item). The group binds remote colour and text styles; code uses the local tokens with the same values (the C19 and C22 principle).

08Guidelines and related components

Do and don't

Common mistakes

• Forgetting current on the last item, so screen readers can't tell which page is open.
• Leaving two breadcrumbs on one page with the same “Breadcrumb” label, which makes their landmarks indistinguishable.
• Using labels that don't match the page headings, so people can't connect the trail to the pages.
• Wrapping BreadcrumbItem in your own <li> or link. It already renders both; use as for a router link.

Related components

• TabsSwitch between views inside the current page.
• Link buttonSingle links and low-emphasis navigation.
• Dropdown menuOverflow for actions and options behind a button.
• IconsRemix icons, including the home icon and the arrow divider.