Components
Breadcrumbs
Use: DeployedExamples - 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 element. |
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