Breadcrumb

A navigation component for displaying a route trail.

Anatomy

Import and assemble the component:

1import { Breadcrumb } from '@raystack/apsara'
2

3<Breadcrumb>
4  <Breadcrumb.Item />
5  <Breadcrumb.Separator />
6  <Breadcrumb.Item />
7  <Breadcrumb.Ellipsis />
8  <Breadcrumb.Item />
9</Breadcrumb>

API Reference

Root

Groups all parts of the breadcrumb navigation.

Prop

Type

Item

Renders an individual breadcrumb link. Use the current prop on the item that represents the current page so it is styled and exposed to assistive tech (e.g. aria-current="page"). Use the disabled prop for non-clickable, visually muted items (e.g. loading or no access).

Item elements expose data attributes for CSS state targeting so you can style current and disabled states without relying on internal class names:

AttributeWhen present
data-current="true"Item is the current page (current prop)
data-disabled="true"Item is disabled (disabled prop)

Example:

1[data-current="true"] {
2  color: var(--my-brand);
3}
4[data-disabled="true"] {
5  opacity: 0.6;
6}

Prop

Type

Separator

Renders a visual divider between breadcrumb items.

Prop

Type

Ellipsis

Renders a collapsed indicator for hidden breadcrumb items.

Prop

Type

Examples

Size

The Breadcrumb component supports different sizes to accommodate various design requirements. Specify the size using the size prop.

1<Breadcrumb size="small">
2  <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
3  <Breadcrumb.Separator />
4  <Breadcrumb.Item href="/products">Products</Breadcrumb.Item>
5  <Breadcrumb.Separator />
6  <Breadcrumb.Item href="/products/shoes" current>
7    Shoes
8  </Breadcrumb.Item>
9</Breadcrumb>

Separator

Customize the separator between breadcrumb items using the separator prop.

1<Flex gap="medium" direction="column">
2  <Breadcrumb>
3    <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
4    <Breadcrumb.Separator>|</Breadcrumb.Separator>
5    <Breadcrumb.Item href="/products">Products</Breadcrumb.Item>
6    <Breadcrumb.Separator>|</Breadcrumb.Separator>
7    <Breadcrumb.Item href="/products/shoes" current>
8      Shoes
9    </Breadcrumb.Item>
10  </Breadcrumb>
11  <Breadcrumb>
12    <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
13    <Breadcrumb.Separator>-</Breadcrumb.Separator>
14    <Breadcrumb.Item href="/products">Products</Breadcrumb.Item>
15    <Breadcrumb.Separator>-</Breadcrumb.Separator>

Ellipsis

Use the Breadcrumb.Ellipsis component to truncate the breadcrumb trail when you need to display a large number of items in a limited space.

1<Breadcrumb>
2  <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
3  <Breadcrumb.Separator />
4  <Breadcrumb.Ellipsis />
5  <Breadcrumb.Separator />
6  <Breadcrumb.Item href="/products/shoes" current>
7    Shoes
8  </Breadcrumb.Item>
9</Breadcrumb>

Icons

Breadcrumb items can include icons via leadingIcon (before the label) or trailingIcon (after the label), either alongside text or as standalone elements.

1<Breadcrumb>
2  <Breadcrumb.Item href="/" leadingIcon={<BellIcon />}>
3    Home
4  </Breadcrumb.Item>
5  <Breadcrumb.Separator />
6  <Breadcrumb.Item href="/documents" leadingIcon={<FilterIcon />}>
7    Documents
8  </Breadcrumb.Item>
9  <Breadcrumb.Separator />
10  <Breadcrumb.Item href="/settings" leadingIcon={<ShoppingBagFilledIcon />}>
11    Settings
12  </Breadcrumb.Item>
13</Breadcrumb>

Dropdown

Breadcrumb items can include dropdown menus for additional navigation options. Specify the dropdown items using the dropdownItems prop. Each item can have label, optional href (renders as a link), optional target and rel (e.g. target="_blank" rel="noopener noreferrer" for new tab), and optional onClick.

Note: When dropdownItems is provided, the as and href props on the breadcrumb item are ignored.

1<Breadcrumb>
2  <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
3  <Breadcrumb.Separator />
4  <Breadcrumb.Item href="/category">Category</Breadcrumb.Item>
5  <Breadcrumb.Separator />
6  <Breadcrumb.Item
7    dropdownItems={[
8      {
9        label: "Option 1",
10        onClick: () => {
11          console.log("Option 1");
12        },
13      },
14      {
15        label: "Option 2",
1<Breadcrumb>
2  <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
3  <Breadcrumb.Separator />
4  <Breadcrumb.Item
5    dropdownItems={[
6      {
7        label: "Electronics",
8        href: "/electronics",
9        target: "_blank",
10        rel: "noopener noreferrer",
11      },
12      { label: "Clothing", href: "/clothing" },
13      {
14        label: "Books",
15        onClick: () => {

As

Use the as prop to render the breadcrumb item as a custom component. By default, breadcrumb items are rendered as a tags.

When a custom component is provided, the props are merged, with the custom component's props taking precedence over the breadcrumb item's props.

1<Breadcrumb>
2  <Breadcrumb.Item href="/home" as={<NextLink href="/" />}>
3    Home
4  </Breadcrumb.Item>
5  <Breadcrumb.Separator />
6  <Breadcrumb.Item href="/playground" as={<NextLink />}>
7    Playground
8  </Breadcrumb.Item>
9  <Breadcrumb.Separator />
10  <Breadcrumb.Item href="/docs" current>
11    Docs
12  </Breadcrumb.Item>
13</Breadcrumb>

Disabled

Use the disabled prop for non-clickable, visually muted items—for example, loading states or segments the user does not have access to. Disabled items render as a span with aria-disabled="true" and do not navigate.

1<Breadcrumb>
2  <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
3  <Breadcrumb.Separator />
4  <Breadcrumb.Item disabled>Loading…</Breadcrumb.Item>
5  <Breadcrumb.Separator />
6  <Breadcrumb.Item href="/products" current>
7    Products
8  </Breadcrumb.Item>
9</Breadcrumb>

Accessibility

  • Uses nav element with aria-label="Breadcrumb" for proper landmark identification
  • Current page is indicated with aria-current="page"
  • Disabled items use aria-disabled="true"
  • Separator elements are decorative and use role="presentation" and aria-hidden="true" so screen readers skip them