Components

Breadcrumb

Breadcrumbs provide secondary navigation to help users understand where they are in a website.

Passed WCAG 2.1 AA

About the breadcrumb component

A breadcrumb bar shows the location of the current page in the site structure. It’s like a path from the current page back to the home page, showing each level of organization in-between. Breadcrumbs allow a user to navigate “up” to a parent section instead of “Back” to the previous page. Use breadcrumbs to help users navigate and understand the organization of your site.

Default breadcrumb

Breadcrumb with RDFa metadata

Wrapping breadcrumb

<h3 class="site-preview-heading">Default breadcrumb</h3>
<nav class="usa-breadcrumb" aria-label="Breadcrumbs,,">
  <ol class="usa-breadcrumb__list">
    <li class="usa-breadcrumb__list-item">
      <a href="" class="usa-breadcrumb__link"><span>Home</span></a>
    </li>
    <li class="usa-breadcrumb__list-item">
      <a href="" class="usa-breadcrumb__link"
        ><span>Federal Contracting</span></a
      >
    </li>
    <li class="usa-breadcrumb__list-item">
      <a href="" class="usa-breadcrumb__link"
        ><span>Contracting assistance programs</span></a
      >
    </li>
    <li class="usa-breadcrumb__list-item usa-current" aria-current="page">
      <span
        >Economically disadvantaged women-owned small business federal
        contracting program</span
      >
    </li>
  </ol>
</nav>

<h3 class="site-preview-heading">Breadcrumb with RDFa metadata</h3>
<nav class="usa-breadcrumb" aria-label="Breadcrumbs">
  <ol
    vocab="http://schema.org/"
    typeof="BreadcrumbList"
    class="usa-breadcrumb__list"
  >
    <li
      property="itemListElement"
      typeof="ListItem"
      class="usa-breadcrumb__list-item"
    >
      <a
        property="item"
        typeof="WebPage"
        href="javascript:void(0);"
        class="usa-breadcrumb__link"
        ><span property="name">Home</span></a
      ><meta property="position" content="1" />
    </li>
    <li
      property="itemListElement"
      typeof="ListItem"
      class="usa-breadcrumb__list-item"
    >
      <a
        property="item"
        typeof="WebPage"
        href="javascript:void(0);"
        class="usa-breadcrumb__link"
        ><span property="name">Federal Contracting</span></a
      ><meta property="position" content="2" />
    </li>
    <li
      property="itemListElement"
      typeof="ListItem"
      class="usa-breadcrumb__list-item"
    >
      <a
        property="item"
        typeof="WebPage"
        href="javascript:void(0);"
        class="usa-breadcrumb__link"
        ><span property="name">Contracting assistance programs</span></a
      ><meta property="position" content="3" />
    </li>
    <li
      property="itemListElement"
      typeof="ListItem"
      class="usa-breadcrumb__list-item usa-current"
      aria-current="page"
    >
      <span property="name"
        >Women-owned small business federal contracting program</span
      ><meta property="position" content="4" />
    </li>
  </ol>
</nav>

<h3 class="site-preview-heading">Wrapping breadcrumb</h3>
<nav class="usa-breadcrumb usa-breadcrumb--wrap" aria-label="Breadcrumbs,,,">
  <ol class="usa-breadcrumb__list">
    <li class="usa-breadcrumb__list-item">
      <a href="" class="usa-breadcrumb__link"><span>Home</span></a>
    </li>
    <li class="usa-breadcrumb__list-item">
      <a href="" class="usa-breadcrumb__link"
        ><span>Federal Contracting</span></a
      >
    </li>
    <li class="usa-breadcrumb__list-item">
      <a href="" class="usa-breadcrumb__link"
        ><span>Contracting assistance programs</span></a
      >
    </li>
    <li class="usa-breadcrumb__list-item usa-current" aria-current="page">
      <span
        >Economically disadvantaged women-owned small business federal
        contracting program</span
      >
    </li>
  </ol>
</nav>

When to use the breadcrumb component

  • When orientation matters. Breadcrumbs show where the current page is located in the website hierarchy. Use a breadcrumb when it’s likely that a user will arrive at an interior page from search or from an outside link.
  • To facilitate navigation. Breadcrumbs make it easier to understand complex sites. Use breadcrumbs to reinforce your site’s structure.

When to consider something else

  • Simple sites. If the website is not very deep and the context for the current page is clear from the main navigation.
  • Landing pages. Omit breadcrumbs on the homepage of a site. Breadcrumbs could also be omitted from section landing pages. Breadcrumbs are most useful when the hierarchy is not immediately apparent from the main navigation.
  • Redundant side navigation. When side navigation is used in combination with main navigation, it may be redundant to include breadcrumbs.
  • Step-by-step processes. Use breadcrumbs for hierarchical relationships, not linear relationships (like individual steps in a multi-step process).

Usability guidance

  • Consider alternatives to wrapping. In general, rely on truncating the title of the current page over wrapping breadcrumb text. But usability comes first. Consider alternative approaches if the title of the current page is completely truncated. For example, a mobile-friendly breadcrumb may show only a page’s direct parent. Sites with very long breadcrumb trails might ultimately need to wrap breadcrumbs, or consider flattening the information architecture of the site.
  • Use complete page titles. Use the same wording in breadcrumb text as in the page title.
  • Start with the word “Home”. Rather than using a house icon, spell out the word “Home” as the first link in the breadcrumbs.
  • Consider size of tap targets on small widths. Although breadcrumbs are frequently displayed using smaller text, make sure the text is not too small to select at small widths.
  • Optimize for search engines. To be eligible for rich results display in search engine results, mark up your site’s breadcrumbs using JSON-LD (recommended) or RDFa.

Accessibility guidance

Test the breadcrumb component in your own project.

USWDS tested the breadcrumb component for accessibility. You should test your implementation, too.

Use breadcrumb accessibility tests
  • Use the nav element. This allows assistive technology to present the breadcrumbs in context as a navigational element on the page.
  • Treat separators as text when it comes to contrast. Use separators that have AA contrast against their background.
  • Use ordered lists and list items. Use an ol for breadcrumbs and an li for each item. This allows assistive technology to enumerate the items in the breadcrumbs and allows shortcuts between list items.
  • Use ARIA markup for additional context. Use aria-label="Breadcrumbs" on the main element and aria-current="page" on the current page.
  • Hide separators from screen readers. The separators between links in the breadcrumbs should not be read by screen readers.

Using the breadcrumb component

Breadcrumb settings

Variable Description
$theme-breadcrumb-background-color

The background color of the complete breadcrumb bar. Default uses body background color set in $theme-body-background-color.
$theme-breadcrumb-font-family

The family of the breadcrumb text.
$theme-breadcrumb-font-size

The size of the breadcrumb text.
$theme-breadcrumb-link-color

The color of breadcrumb link. Add the link color and the system will generate the hover state. Default uses the default link settings calculated from your background color.
$theme-breadcrumb-min-width

The width at which the breadcrumb displays the full breadcrumb list.
$theme-breadcrumb-padding-bottom

Padding below the breadcrumb.
$theme-breadcrumb-padding-top

Padding above the breadcrumb.
$theme-breadcrumb-padding-x

Padding to the right and left of the breadcrumb.
$theme-breadcrumb-separator-color

Color of the breadcrumb separator. This value needs AA contrast against the background.

Breadcrumb variants

Variant Description

.usa-breadcrumb--wrap

Wrap the breadcrumb bar instead of truncating.

Accessibility test status

The USWDS team did 14 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
14 11 0 3 0

Overview of recent accessibility test results:

  • Passed: 11
  • Passed with exceptions: 0
  • Conditional: 3
  • Failed: 0

Learn more on the breadcrumb accessibility tests page.

  • Package usage: @forward "usa-breadcrumb";
  • Dependencies: uswds-fonts, usa-icon

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-10-16 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2853

2023-09-29 3.6.1
  • Styles
 No

Fixed a bug that prevented text from wrapping to a new line in the .usa-breadcrumb--wrap variant. More information: uswds#5497

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2021-08-18 2.12.1
  • Accessibility
  • Styles
 No

Updated breadcrumb to work with a broader range of focus widths. Now the breadcrumb component isn’t affected by custom focus widths. More information: uswds#4248