Breadcrumbs provide secondary navigation to help users understand where they are in a website.
About the breadcrumb component
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).
- 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.
- Use the
navelement. 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
olfor breadcrumbs and an
lifor 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
The background color of the complete breadcrumb bar.
The family of the breadcrumb text.
The size of the breadcrumb text.
The color of breadcrumb link. Add the link color and the system will generate the hover state.
The width at which the breadcrumb displays the full breadcrumb list.
Padding below the breadcrumb.
Padding above the breadcrumb.
Padding to the right and left of the breadcrumb.
Color of the breadcrumb separator. This value needs AA contrast against the background.
Wrap the breadcrumb bar instead of truncating.
Meaningful code and guidance updates are listed in the following table:
Fixed a bug that prevented text from wrapping to a new line in the
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656
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