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 register and profile, to show the hierarchy of parent and child pages in the context of the current page where the current page is the last item in the list.

When not to use

  • If you need to link to sibling or related pages, use a form of navigation instead.


  • An avatar can appear to the left of the text for any group, project, or user link 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


  • Use an ellipsis button to hide groups when there are three or more subgroups in the path.
  • Use an ellipsis button to hide all Wiki page breadcrumb items except the current page.
  • The top-level group and the subgroup closest to the project are never collapsed.
  • All breadcrumb items, except the last one, are truncated to 128px if there isn't enough horizontal space to fit them on one line.


  • Ignore the GitLab instance name in the breadcrumb.
  • 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 element of the breadcrumb should include the ID of the element. For example, merge request !1234 becomes > GitLab > Merge requests > !1234.
  • For a contextual page within the navigation, the breadcrumb should only include the submenu title. For example, Overview > Details becomes just Details.
  • Use sentence case for each breadcrumb element.

Special breadcrumbs

Some pages have a special breadcrumb path to make the text intuitive. They are defined as follows:

PathTitle in breadcrumb
Group > Issues > ListGroup > Issues
Group > Issues > BoardsGroup > Issue boards
Group > Settings > GeneralGroup > General settings
Group > Settings > CI / CDGroup > CI / CD settings
Group > Project > Repository > FilesGroup > Project > Repository
Group > Project > Repository > CompareGroup > Project > Compare revisions
Group > Project > Repository > ChartsGroup > Project > Contribution charts
Group > Project > Issues > ListGroup > Project > Issues
Group > Project > Issues > BoardsGroup > Project > Issue boards
Group > Project > CI / CD > ChartsGroup > Project > CI/CD charts
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 > Label > 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: