Usage

import { Breadcrumb, Breadcrumbs } from "@opengovsg/oui"

<Breadcrumbs>
  <Breadcrumb href="#">Home</Breadcrumb>
  <Breadcrumb href="#">Components</Breadcrumb>
  <Breadcrumb>Breadcrumbs</Breadcrumb>
</Breadcrumbs>

OUI exports 2 breadcrumb-related components:

• Breadcrumbs: The container component that provides context and layout for breadcrumb items.
• Breadcrumb: An individual breadcrumb item, rendered as a link by default. The last item is automatically styled as the current page.

Examples

Custom Separator

Use the separator prop to change the separator between breadcrumb items. The default separator is a chevron icon. You can pass any string (e.g. "/", "|") or a custom React node.

Disabled

Use the isDisabled prop to disable all breadcrumb items, preventing navigation while maintaining layout consistency.

Truncation

When breadcrumbs have many items, you can use the itemsBeforeTruncate prop to collapse middle items behind an ellipsis. Clicking the ellipsis opens a dropdown menu showing the hidden items.

Use itemsAfterTruncate to control how many items are shown after the ellipsis (default: 2).

Note: Truncation props are ignored when using the Collection API (items prop). These two modes are mutually exclusive and this is enforced at the type level.

Truncation Without Dropdown

Set renderTruncate={null} to display the ellipsis without an interactive dropdown.

Custom Truncation Dropdown

Pass a custom render function to renderTruncate to fully control the dropdown content and styling.

Collection API

As an alternative to JSX children, you can use the Collection API by passing an items array. Items are rendered using a render function.

Note: The Collection API cannot be used simultaneously with truncation props (itemsBeforeTruncate, itemsAfterTruncate, renderTruncate). This is enforced at the type level.

Custom Breadcrumb Content

Breadcrumb items accept arbitrary content. For example, you can embed a MenuTrigger inside a breadcrumb to create a dropdown navigation item.

Slots

• base: The outer container of the breadcrumbs list.
• crumb: The wrapper for each individual breadcrumb item.
• link: The link element inside each breadcrumb.
• separator: The separator element between breadcrumb items.
• ellipsisTrigger: The trigger element for the truncation ellipsis.

Custom Styles

You can customize the Breadcrumbs component by passing custom Tailwind CSS classes to the component slots via the classNames prop.

<Breadcrumbs
  classNames={{
    base: "gap-2",
    crumb: "gap-2",
    link: "text-brand-primary-500",
    separator: "text-base-content-medium",
  }}
>
  <Breadcrumb>Home</Breadcrumb>
</Breadcrumbs>

Individual Breadcrumb items also accept a classNames prop to override styles on a per-item basis (all slots except base).

<Breadcrumb
  classNames={{
    crumb: "font-bold",
    link: "text-brand-primary-700",
    separator: "text-base-content-strong",
  }}
>
  Highlighted
</Breadcrumb>

Accessibility

• Breadcrumbs are rendered as an ordered list (<ol>) inside a <nav> element, providing semantic navigation structure.
• The last breadcrumb item is automatically marked as the current page with aria-current="page".
• Separators are hidden from assistive technologies with aria-hidden.
• The truncation ellipsis has an aria-label of "Show more breadcrumbs" for screen readers.
• Full keyboard navigation is supported.

Props

Breadcrumbs

Breadcrumb

BreadcrumbEllipsisItem

The shape of items passed to the renderTruncate function.