Breadcrumb
A breadcrumb is a navigational element to help a user understand the current location in the application as well as content structure and hierarchy.
Examples
Breadcrumb
Loading story...
Collapsed
Loading story...
Structure
- Avatar (optional): Prefixes a group or project link.
- Link: Opens the page in the same window.
- Separator: A forward slash character
/
separates each link.
Guidelines
When to use
- A breadcrumb should exist on every page of the application, except for the register and sign in page, to show the hierarchy in the context of the current page.
When not to use
- If you need to link to sibling or related pages.
Appearance
- An avatar can appear to the left of the text for any group or project in the breadcrumb.
- A bottom border may be applied to a parent container to visually distinguish the breadcrumb from the content of the page.
TODO:
Update border related appearance notes as a result of
!3262
.
Create an issue
Behavior
- The full breadcrumb path should remain visible when there's enough horizontal space to fit on one line.
- When space is limited, use an ellipsis button to collapse links from left to right.
- Collapsed items are revealed with a flat hierarchy in a simple disclosure dropdown when selecting the ellipsis button.
- All but the last breadcrumb item is truncated to 128px if there isn't enough horizontal space to fit them on one line.
Content
- Ignore the GitLab instance name in the breadcrumb.
- Every item must contain a link to the page it's associated with.
- The breadcrumb should include the name of the context matching the navigation sidebar.
- For a page that presents the details of an individual item (issue, merge request, snippet, pipeline, job, milestone, commit, tag, environment, cluster, pipeline schedule), the last breadcrumb element should include the element's ID. For example, merge request !1234 is represented as GitLab.org / GitLab / Merge requests / !1234.
- For a page that allows a user to create a new item, the last breadcrumb element should include the word New followed by the name of the element. For example, GitLab.org / GitLab / Issues / New becomes GitLab.org / GitLab / Issues / New issue. Only using the New text may cause confusion when translating GitLab into different languages.
- Use sentence case for each breadcrumb element.
- Collection titles that group primary navigation sections are not included in the breadcrumb.
Special breadcrumbs
Some pages have a special breadcrumb path to make the text intuitive. They are defined as follows:
Path | Title in breadcrumb |
---|---|
Group / Settings / General | Group / General settings |
Group / Settings / CI/CD | Group / CI/CD settings |
Group / Project / Repository / Compare | Group / Project / Compare revisions |
Group / Project / Repository graph | Group / Project / Graph |
Group / Project / Settings / General | Group / Project / General settings |
Group / Project / Settings / Integrations | Group / Project / Integration settings |
Group / Project / Settings / Repository | Group / Project / Repository settings |
Group / Project / Settings / CI/CD | Group / Project / CI/CD settings |
User settings / Profile | User settings / Edit profile |
User settings / Password | User settings / Edit password |
Admin area / System hooks / Edit | Admin area / System hooks / Edit system hook |
Admin area / Labels / Edit | Admin area / Labels / Edit label |
Accessibility
- A
nav
element witharia-label="Breadcrumb"
wraps an ordered list to provide a navigation landmark. - Ensure the last item in a breadcrumb is a link (rather than plain text) so it's included in the focus order. Added benefits of doing so include making it easy to generate a pristine page link (without a trailing anchor reference to a heading, diff, comment, or other location within the page) or to refresh the page.
aria-current="page"
is on the last link to indicate that it's the current page.- See the WAI-ARIA Authoring Practices Breadcrumb Example for more details.
Last updated at: