A breadcrumb is a navigational element to help a user understand the current location in the application as well as content structure and hierarchy.


Loading story...
Loading story...

View in Pajamas UI Kit →


Numbered diagram of a breadcrumb structure
Breadcrumb structure
  1. Avatar (optional): Prefixes a group or project link.
  2. Link: Opens the page in the same window.
  3. Separator: A forward slash character / separates each link.


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.


  • 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.
Update border related appearance notes as a result of !3262 . Create an issue


  • 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.


  • 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 / 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 / Issues / New becomes / 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:

PathTitle in breadcrumb
Group / Settings / GeneralGroup / General settings
Group / Settings / CI/CDGroup / CI/CD settings
Group / Project / Repository / CompareGroup / Project / Compare revisions
Group / Project / Repository graphGroup / Project / Graph
Group / Project / Settings / GeneralGroup / Project / General settings
Group / Project / Settings / IntegrationsGroup / Project / Integration settings
Group / Project / Settings / RepositoryGroup / Project / Repository settings
Group / Project / Settings / CI/CDGroup / Project / CI/CD settings
User settings / ProfileUser settings / Edit profile
User settings / PasswordUser settings / Edit password
Admin area / System hooks / EditAdmin area / System hooks / Edit system hook
Admin area / Labels / EditAdmin area / Labels / Edit label


  • A nav element with aria-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: