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

base-breadcrumb--default
Loading story...

View in Pajamas UI Kit →

Structure

Numbered diagram of a breadcrumb structure
  1. Avatar (optional): Prefixes a group or project link.
  2. Link: Opens the page in the same window.
  3. Separator: The chevron-right icon is between each link.

Guidelines

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.

Behavior

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

Content

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

Accessibility

  • A nav element with aria-label="Breadcrumb" wraps an ordered list to provide a navigation landmark.
  • 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: