Breadcrumbs (Preview)

To add the Breadcrumbs and BreadcrumbsItem components to your app:

1
2
import { Breadcrumbs, BreadcrumbsItem } from '@forge/react';

Description

Breadcrumbs are a navigation system used to show a user's location in a site or app.

Props

Breadcrumbs

BreadcrumbsItem

Examples

Default

The default breadcrumbs with a series of linked items.

1
2
const BreadcrumbsDefaultExample = () => {
  return (
    <Breadcrumbs>
      <BreadcrumbsItem href="https://www.atlassian.com" text="Atlassian" />
      <BreadcrumbsItem href="https://www.atlassian.com/software/jira" text="Jira" />
      <BreadcrumbsItem text="Project" />
    </Breadcrumbs>
  );
};

Max items

Use the maxItems prop to limit the number of visible breadcrumb items. When the number of items exceeds maxItems, the middle items collapse into an ellipsis that can be expanded.

1
2
const BreadcrumbsMaxItemsExample = () => {
  return (
    <Breadcrumbs maxItems={3}>
      <BreadcrumbsItem href="https://www.atlassian.com" text="Atlassian" />
      <BreadcrumbsItem href="https://www.atlassian.com/software" text="Software" />
      <BreadcrumbsItem href="https://www.atlassian.com/software/jira" text="Jira" />
      <BreadcrumbsItem href="https://www.atlassian.com/software/jira/projects" text="Projects" />
      <BreadcrumbsItem text="My Project" />
    </Breadcrumbs>
  );
};

With icons

Use iconBefore and iconAfter on BreadcrumbsItem to add icons to individual breadcrumb items.

1
2
const BreadcrumbsWithIconsExample = () => {
  return (
    <Breadcrumbs>
      <BreadcrumbsItem
        href="https://www.atlassian.com"
        text="Home"
        iconBefore="home"
      />
      <BreadcrumbsItem
        href="https://www.atlassian.com/software/jira"
        text="Jira"
      />
      <BreadcrumbsItem text="Project" iconAfter="chevron-right" />
    </Breadcrumbs>
  );
};

Default expanded

Use defaultExpanded to show all breadcrumb items expanded on initial render, even when the number of items exceeds maxItems.

1
2
const BreadcrumbsDefaultExpandedExample = () => {
  return (
    <Breadcrumbs maxItems={2} defaultExpanded>
      <BreadcrumbsItem href="https://www.atlassian.com" text="Atlassian" />
      <BreadcrumbsItem href="https://www.atlassian.com/software/jira" text="Jira" />
      <BreadcrumbsItem text="Project" />
    </Breadcrumbs>
  );
};

Usage guidelines

Breadcrumbs are a navigation component and work best in large, full-page app experiences where users move between hierarchical views. We recommend using Breadcrumbs only in the following extension points:

• globalPage: Global page apps accessible from the side navigation.
• fullPage: Full page Confluence and Jira app experiences

Using breadcrumbs in smaller embedded contexts (e.g. macros or content bylines) can result in a poor user experience. Navigation patterns in compact embedded surfaces typically conflict with the parent app’s navigation.

Accessibility considerations

When using the Breadcrumbs and BreadcrumbsItem components, we recommend keeping the following accessibility considerations in mind:

• Use the label prop to provide a descriptive name for the breadcrumb navigation region so that assistive technologies can distinguish it from other navigation landmarks on the page.
• Use the ellipsisLabel prop to provide a meaningful label for the collapse/expand button so that screen reader users understand its purpose.
• Ensure each breadcrumb item's text clearly describes the page or location it links to. Avoid generic labels like "Click here".
• The last item in a breadcrumb trail typically represents the current page and should not have an href.