# Breadcrumb

Component of the SBB design system Lyne.

- Package: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Structure: one element with optional grouping
- Categories: Navigation
- Status: Design guidelines complete

## Links

- Page on digital.sbb.ch: https://digital.sbb.ch/en/design-system/lyne/components/breadcrumb/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-breadcrumb--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/breadcrumb/overview (API: https://lyne-angular.app.sbb.ch/angular/components/breadcrumb/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=7491-15
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/breadcrumb

## Elements

- `sbb-breadcrumb`, several can be combined with `sbb-breadcrumb-group`: It displays a link to a page; used within a `sbb-breadcrumb-group` it can display the path to the current page.

## Overview

### What does the component do?
A breadcrumb group is a navigation aid. It shows users where they are within the hierarchy of a website and allows them to jump to higher-level pages.

### When should the component be used?
* To show the current location within the website structure.
* To make navigation easier on pages with deep hierarchies.

### Rules.
* The breadcrumb group always starts at the home page and shows the complete path to the current page.
* The individual levels are labelled clearly and understandably.
* It shows no more than 5–7 levels. If there is not enough space, only the first and the last level are shown with "…" in between. Clicking it shows all levels again.
* The first level (home page) is displayed with an icon only.
* The breadcrumb group needs an `aria-label` describing its context. The current page is automatically marked for screen readers.

## Implementation (web components)

The `<sbb-breadcrumb>` and `<sbb-breadcrumb-group>` components are meant to represent the hierarchy of visited pages before arriving to the current one.

The `<sbb-breadcrumb>` is equivalent to a native [anchor (a)](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a) element.

```html
<sbb-breadcrumb-group aria-label="You are here:">
  <sbb-breadcrumb href="/" icon-name="house-small"></sbb-breadcrumb>
  <sbb-breadcrumb href="/work-with-us"> Work with us </sbb-breadcrumb>
  <sbb-breadcrumb href="/apply" target="_blank"> Apply </sbb-breadcrumb>
</sbb-breadcrumb-group>
```

### Slots

For the `<sbb-breadcrumb>` it is possible to provide a text via an unnamed slot; the component can optionally display a `<sbb-icon>`
at the component start using the `iconName` property or via custom content using the `icon` slot.
Text and icon are not exclusive and can be used together.

```html
<sbb-breadcrumb href="/contact">Contact us</sbb-breadcrumb>

<sbb-breadcrumb href="/book-your-trip" icon-name="travel-backpack-medium"></sbb-breadcrumb>

<sbb-breadcrumb href="/info">
  Info
  <sbb-icon slot="icon" name="circle-information-small"></sbb-icon>
</sbb-breadcrumb>
```

### Link properties

It's possible to set all the link related properties (`download`, `href`, `rel` and `target`).

```html
<sbb-breadcrumb href="/info" target="_blank" rel="help">Info</sbb-breadcrumb>
```

### Style

If the width of all the nested `<sbb-breadcrumb>` exceeds the container width,
only the first and the last breadcrumb are displayed, and a new one with the ellipsis symbol appears between them.
Clicking on this `<sbb-breadcrumb>` will make the ellipsis disappear and will restore the full list
(the action is not reversible).

### Accessibility

The `accessibility-current` property should be used to make the breadcrumb read correctly by screen-readers when the component
is used in the `<sbb-breadcrumb-group>`.

By default, the `<sbb-breadcrumb-group>` component sets `accessibility-current="page"` on the last slotted `<sbb-breadcrumb>`.

It is strongly recommended to place an `aria-label` attribute on the `<sbb-breadcrumb-group>`, as in the example above,
to describe what context the breadcrumbs have.
Whenever the `<sbb-breadcrumb>` list within the component is loaded or updated,
the last element of the list receives the attribute `accessibility-current="page"`.

## API (web components)

Full API tables (attributes, events, slots, CSS properties): https://digital.sbb.ch/en/design-system/lyne/components/breadcrumb/api.md