Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

Breadcrumbs

Use: Deployed USWDS v3
Breadcrumbs provide secondary navigation to help users understand where they are in a website. In addition, the breadcrumb tells search engines how the site is structured, and it can be displayed in search results. This can improve rankings, and provide users with additional context.

Examples - v1

Default

View va-breadcrumbs in Storybook

Rerender state

View va-breadcrumbs and adjust state in Storybook

Examples - v3

Default

View va-breadcrumbs in Storybook

Rerender state

View va-breadcrumbs v3 and adjust state in Storybook

Wrapping state

View va-breadcrumbs v3 wrapping state in Storybook

Usage

Refer to the U.S. Web Design System for usage guidance

Additional guidance for VA

When to use

  • Complex levels. Use a breadcrumb when content is more than 2 levels deep.

When to consider something else

  • Simple sites. Do not use a breadcrumb if the site or experience has a flat structure (i.e. only 2 levels of content or less)
  • Irrelevant hierarchy. Do not use a breadcrumb if the path or hierarchy of the page is irrelevant to the user or experience.
  • One way exit. Do not use a breadcrumb if it would create a way for a user to exit or navigate away from a user flow that they are unable to return to, or would result in a loss of data.

Usability guidance

  • Breadcrumbs should be based on content hierarchy, not on the user’s click path or browser history. For online applications and forms, the breadcrumb represents the forms’s placement within the site hierarchy, it does not track the steps or progress of the form flow. In other words, the breadcrumb will only show up to the form as the current page segment, and will maintain that display while the user goes through the flow. For navigation through the steps of the form flow, forward and backward CTAs can be provided as part of the main content as appropriate.
  • Include one, include all. If you use a breadcrumb for one page in a hierarchy, always use a breadcrumb for all pages within that hierarchy.
  • Each breadcrumb segment should match the H1 of the corresponding page. When writing H1s for a page, follow the content styleguide for writing page titles.

Placement

  • The breadcrumb should be placed below the header and above the main content.
  • The placement of the breadcrumb must be consistent from page to page.

Behavior

  • All the links in the breadcrumb, except the current page, should be interactive and link to their corresponding page.
  • The current page segment of the breadcrumb should not be interactive or link.

SEO considerations

  • Search engines utilize breadcrumbs to understand your site structure and gain additional context about your page to help in ranking.
  • Breadcrumbs can also be displayed in search engine results pages (SERPs), which provides additional context to users about your page.
  • Breadcrumbs are not the only element used by search engines, go to writing for SEO in the content styleguide for more SEO assistance.

Code usage

Attributes and Properties

Property Attribute Type Default Description
breadcrumbList breadcrumb-list any Represents a list of breadcrumbs. Use an array of objects with label and href properties, and then use JSON.stringify() to convert to a string. This prop is available when `uswds` is set to `true`.
disableAnalytics disable-analytics boolean false Analytics tracking function(s) will not be called
label label string 'Breadcrumb' Adds an aria-label attribute to the
uswds uswds boolean false Whether or not the component will use USWDS v3 styling.
wrapping wrapping boolean false Whether or not the component will wrap the breadcrumbs. This prop is available when `uswds` is set to `true`.

Events

Name Description
component-library-analytics The event used to track usage of the component. This is emitted when a breadcrumb anchor is clicked and disableAnalytics is not true.

Accessibility considerations

Refer to the U.S. Web Design System for accessibility guidance

Edit this page in GitHub (Permissions required)
Last updated: Aug 17, 2023