Breadcrumb

A breadcrumb (or “breadcrumb trail”) is a type of secondary navigation that reveals the user’s location in a website or web application.

Usage

When to use

• To display the hierarchy and location of the current page.
• While not required for every page, a breadcrumb is highly encouraged for the majority of pages with the exception of high-level overviews and dedicated workflows.

When not to use

• As links outside of the page header.
• Within a body of text, use InlineLink
• As a standalone element or within a Button Set, use a StandaloneLink

Item types

Text only

With icon

Truncated

Icons

• Icons should only be added to the first three levels to avoid unnecessary visual noise.
• Icon usage should be inherited and not randomly added to a level (if a higher level uses an icon, the level just under it can also use one).

Truncation

If truncation is needed due to depth or lack of space, use one of the following options. Breadcrumbs will truncate using truncate middle if there are more than five items to display. Truncate middle is recommended unless space is an issue.

Truncate middle

Truncate squeeze

Each text-based item can truncate using a pixel-based max-width at the discretion users discretion. This option should be reserved for instances when items have long text strings.

Width-based

Width-based (Hover)

Dropdowns

For truncated breadcrumb items, clicking, pressing enter, or pressing spacebar will open the truncated dropdown. The truncated dropdown will align to the left side of the breadcrumb item and will be placed 4px below the breadcrumb item.

Truncated dropdowns will include all of the hierarchal layers that have been hidden.

Truncated dropdown

How to use this component

The breadcrumb is an application-level UI element, so it’s likely that it will be implemented once per application.

Basic use

<Hds::Breadcrumb>
  <Hds::Breadcrumb::Item @text="My org" @icon="org" />
  <Hds::Breadcrumb::Item @text="Consul" @icon="consul" />
  <Hds::Breadcrumb::Item @text="my-consul-cluster" />
  <Hds::Breadcrumb::Item @text="Overview" @current={{true}} />
</Hds::Breadcrumb>

With routing parameters

In the basic example a few parameters are omitted for clarity. In reality, each breadcrumb item is expected to be a link, in order to work, the correct @route/@models/@model/@query parameter needs to be passed to the breadcrumb container:

<Hds::Breadcrumb>
  <Hds::Breadcrumb::Item @text="My org" @icon="org" @route="components" />
  <Hds::Breadcrumb::Item @text="Consul" @icon="consul" @route="components" />
  <Hds::Breadcrumb::Item
    @text="my-consul-cluster"
    @route="components"
    @model={{@cluster.id}}
  />
  <Hds::Breadcrumb::Item @text="Overview" @current={{true}} />
</Hds::Breadcrumb>

No wrapping

By default, the breadcrumb allows items to wrap on multiple lines if the container width is too small. If you don’t want this to happen, pass false to the itemsCanWrap parameter, but keep in mind that the text will be automatically replaced with an ellipsis to fit the container:

<Hds::Breadcrumb @itemsCanWrap={{false}}>
  [items here]
</Hds::Breadcrumb>

With truncation

It is also possible to collect and hide part of the breadcrumb tree under a "truncated" item that will show the elements via "toggle":

<Hds::Breadcrumb>
  <Hds::Breadcrumb::Truncation>
    <Hds::Breadcrumb::Item @text="My org" @icon="org" @route="components" />
    <Hds::Breadcrumb::Item @text="Consul" @icon="consul" @route="components" />
    <Hds::Breadcrumb::Item @text="my-consul-cluster" @route="components" />
  </Hds::Breadcrumb::Truncation>
  <Hds::Breadcrumb::Item @text="Cluster details" @route="components" />
  <Hds::Breadcrumb::Item @text="Cluster sub-details" @current={{true}} />
</Hds::Breadcrumb>

Component API

The breadcrumb component is composed of three different parts, each with their own APIs:

• a main “container” (the breadcrumb itself)
• an “item” child component (a single “crumb”)
• a “truncation” child component (a hidden list of “crumbs” that can be made visible via a toggle)

Breadcrumb container

Breadcrumb::Item

Breadcrumb::Truncation

Anatomy

Breadcrumb item

Breadcrumb container

States

Default

Hover

Active

Focus

Conformance status

This component has been designed and implemented with accessibility in mind. However, if the truncation feature is used, this component would not pass a WCAG conformance audit.

Known issues

When the browser zoom is used to scale content to 400%, if the breadcrumb has a "truncation" open, the dropdown may extend beyond the viewport and require the user to scroll in more than one direction (this is a failure of Reflow – 1.4.10).

When the browser zoom is used to scale content to 400%, if the breadcrumb is not allowed to wrap its items (via the @itemsCanWrap prop) the text will likely get truncated, making it impossible for a keyboard-only user to access the truncated content.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, please let us know by submitting an issue.