# Image

Component of the SBB design system Lyne.

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

## Links

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

## Elements

- `sbb-image`: It displays an image.

## Overview

### What does the component do?
The image component displays an image. It preferably loads images from the SBB Image CDN and delivers them in a suitable size for the respective device.

### When should the component be used?
* To visually support and complement content.
* To present complex information or data graphically.
* To create a mood.

### Rules.
* Images are of high quality and have an appropriate resolution.
* Informative images have a descriptive alt text. Decorative images have an empty alt text or are hidden from screen readers.
* Images are responsive and adapt to different screen sizes.
* Images outside the visible area are loaded lazily (lazy loading) to reduce load time.
* An image with a caption or chip label is placed together with it in a `figure` element.
* The predefined utility classes are used for aspect ratio and corner radius.
* Image rights must be cleared.

## Implementation (web components)

The `<sbb-image>` component is used to render an image.

Mainly from cdn.img.sbb.ch (with `imageSrc`), but we can set an external image too.
The size can be set with `pictureSizesConfig`.

```html
<sbb-image image-src="..." alt="..."></sbb-image>
```

### Usage

For image related elements, it is strongly recommended to wrap an `<sbb-image>` and all its related elements in a `figure` tag.
E.g. `<figcaption>` or `<sbb-chip-label>`.

```html
<figure class="sbb-figure">
  <sbb-image ...></sbb-image> or <img />
  <figcaption>Caption / Copyright</figcaption>
</figure>
```

You can place overlapping content by using the `sbb-figure-overlap-${horizontal-alignment}-${vertical-alignment}` utility classes.

| Position       | CSS class                        |
| -------------- | -------------------------------- |
| `top-left`     | `sbb-figure-overlap-start-start` |
| `top-right`    | `sbb-figure-overlap-start-end`   |
| `bottom-left`  | `sbb-figure-overlap-end-start`   |
| `bottom-right` | `sbb-figure-overlap-end-end`     |

```html
<figure class="sbb-figure">
  <sbb-image ...></sbb-image>
  <sbb-chip-label class="sbb-figure-overlap-start-start"></sbb-chip-label>
</figure>
```

Instead of a `<sbb-chip-label>`, it's also possible to slot images (e.g. logos).
In that case, the `sbb-figure-overlap-image` CSS class needs to be set on the image.

```html
<figure class="sbb-figure">
  <sbb-image ...></sbb-image>
  <img class="sbb-figure-overlap-image sbb-figure-overlap-end-end" src="logo.png" alt="Logo" />
</figure>
```

** Multiple `<sbb-chip-label>`s **

In order to place multiple `<sbb-chip-label>`s, a wrapping div can be used:

```html
<figure class="sbb-figure">
  <sbb-image ...></sbb-image>
  <div class="sbb-figure-overlap-end-end">
    <sbb-chip-label>AI generated</sbb-chip-label>
    <sbb-chip-label>Paid content</sbb-chip-label>
  </div>
</figure>
```

#### Utility classes

Use the `sbb-image-border-radius-${value}` utility classes to set the image border radius.

| Border radius | CSS class                         |
| ------------- | --------------------------------- |
| `default`     | `sbb-image-border-radius-default` |
| `none`        | `sbb-image-border-radius-none`    |
| `round`       | `sbb-image-border-radius-round`   |

```html
<sbb-image class="sbb-image-border-radius-none"></sbb-image>
<!-- or -->
<img class="sbb-image-border-radius-round" />
```

Use the `sbb-image-${ratio}` utility classes to set the image aspect ratio.

| Aspect Ratio | CSS class        |
| ------------ | ---------------- |
| `free`       | `sbb-image-free` |
| `1-1`        | `sbb-image-1-1`  |
| `1-2`        | `sbb-image-1-2`  |
| `2-1`        | `sbb-image-2-1`  |
| `2-3`        | `sbb-image-2-3`  |
| `3-2`        | `sbb-image-3-2`  |
| `3-4`        | `sbb-image-3-4`  |
| `4-3`        | `sbb-image-4-3`  |
| `4-5`        | `sbb-image-4-5`  |
| `5-4`        | `sbb-image-5-4`  |
| `9-16`       | `sbb-image-9-16` |
| `16-9`       | `sbb-image-16-9` |

```html
<sbb-image class="sbb-image-16-9"></sbb-image>
<!-- or -->
<img class="sbb-image-4-3" />
```

## API (web components)

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