# Teaser

Component of the SBB design system Lyne.

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

## Links

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

## Elements

- `sbb-teaser` (also as `sbb-teaser-static`): It displays an interactive image with caption.

## Related components

- Similar: [Teaser-Hero](https://digital.sbb.ch/en/design-system/lyne/components/teaser-hero/index.md), [Teaser-Product](https://digital.sbb.ch/en/design-system/lyne/components/teaser-product/index.md)

## Overview

### What does the component do?
A teaser is a preview made of an image and a description. It should arouse users' curiosity and encourage them to click on further content or pages.

### When should the component be used?
* To highlight content, articles, products or services.
* To make users aware of further information.

### Rules.
* Use a concise headline and a short, interesting description.
* The teaser as a whole is a link and needs an `accessibilityLabel`.
* If the teaser contains its own interactive elements, use the teaser static.
* Do not use too many different teaser types and sizes on one page.
* Several teasers can be structured with one title.

## Implementation (web components)

The `<sbb-teaser>` is a component which can display an image with a caption, and it behaves like a link on user interaction.

Use the `<sbb-teaser-static>` variant instead, if the teaser must not behave like a link itself,
e.g. because it already contains one or more interactive/focusable elements
(more than a single static action is not supported within a link).

Simple teaser example:

```html
<sbb-teaser href="https://www.sbb.ch">
  <img slot="image" src="..." alt="400x300" />
  <sbb-chip-label>Chip label</sbb-chip-label>
  <sbb-title level="2">Title</sbb-title>
  A brief description.
</sbb-teaser>
```

### Slots

The default slot is reserved for the description and,
optionally, a [sbb-title](https://lyne-elements.app.sbb.ch/?path=/docs/elements-title--docs) and a [sbb-chip-label](https://lyne-elements.app.sbb.ch/?path=/docs/elements-chip-label--docs).
The component displays the `image` with the self-named slot.

Use the `image` slot to pass a `figure` containing an `<sbb-image>` or an `img` that will be used as background.
Optionally, you can add an overlapping `<sbb-chip-label>` to the slotted `figure` (see [sbb-image doc](https://lyne-elements.app.sbb.ch/?path=/docs/elements-image--docs#utility-classes)).

```html
<sbb-teaser href="https://www.sbb.ch">
  <figure slot="image" class="sbb-figure">
    <img src="..." alt="400x300" />
    <sbb-chip-label class="sbb-figure-overlap-start-start">AI Generated</sbb-chip-label>
  </figure>
  <sbb-chip-label>Chip label</sbb-chip-label>
  <sbb-title level="2">Title</sbb-title>
  A brief description.
</sbb-teaser>
```

Use the `action` slot to display a static action
e.g. a [sbb-secondary-button-static](https://lyne-elements.app.sbb.ch/?path=/docs/elements-button-secondary-button-static--docs) within an `<sbb-teaser>` element
or interactive action (e.g. a [sbb-secondary-button-link](https://lyne-elements.app.sbb.ch/?path=/docs/elements-button-secondary-button-link--docs) within a `<sbb-teaser-static>` element)
below the description.
Lyne buttons are automatically assigned to the `action` slot when slotted in the default slot.

```html
<sbb-teaser href="https://www.sbb.ch">
  <img slot="image" src="..." alt="400x300" />
  <sbb-chip-label>Chip label</sbb-chip-label>
  <sbb-title level="2">Title</sbb-title>
  A brief description.
  <sbb-secondary-button-static>Read more</sbb-secondary-button-static>
</sbb-teaser>
```

### Style

Using the `alignment` property, it is possible to change the text position respect to the image.
Possible values are `before`, `after-centered`, `after-centered` (default), `after` and `below`.

```html
<sbb-teaser href="https://www.sbb.ch" alignment="below"> ... </sbb-teaser>
```

The component has two different sizes (`m` and `l`), which can be changed using the `size` property.
The size defaults to `m` in both the standard and the lean theme.

```html
<sbb-teaser size="l" href="https://www.sbb.ch"> ... </sbb-teaser>
```

By default, the image dimensions are set using the width and the aspect ratio.
Default values are `300px` and `4/3`. Consumers can change these values on their slotted image element.

#### Flexible Layouts

If using the teaser in a flexible layout like CSS grid or flex together with `alignment=below`,
the CSS variable `--sbb-teaser-align-items` with `stretch` as value can be used
to achieve the image width taking the full available space. On the image itself, the width must be set to `100%`.

```html
<div style="display: grid; gap: 1rem; grid-template-rows: repeat(2, 1fr)">
  <sbb-teaser style="--sbb-teaser-align-items: stretch" href="https://www.sbb.ch" alignment="below">
    <sbb-image style="width: 100%;" slot="image" image-src="..." alt="description"></sbb-image>
    ...
  </sbb-teaser>
  <sbb-teaser style="--sbb-teaser-align-items: stretch" href="https://www.sbb.ch" alignment="below">
    <sbb-image style="width: 100%;" slot="image" image-src="..." alt="description"></sbb-image>
    ...
  </sbb-teaser>
</div>
```

### Accessibility

It's important to set the `accessibilityLabel` on the `<sbb-teaser>`, which describes the `<sbb-teaser>` for screen-reader users.

The description text is wrapped into an `<p>` element to guarantee the semantic meaning.

### Static variant

The `<sbb-teaser-static>` is a non-interactive version of the `<sbb-teaser>` component.
Unlike `<sbb-teaser>`, it does not render an anchor and therefore has no `href`, `target`, `rel`,
`download`, `accessibilityLabel` or `accessibilityCurrent` property.
It should be used whenever the teaser has to contain more than one interactive element,
e.g. multiple links or buttons, since nesting interactive elements inside a link is not allowed.

```html
<sbb-teaser-static>
  <img slot="image" src="..." alt="400x300" />
  <sbb-chip-label>Chip label</sbb-chip-label>
  <sbb-title level="2">Title</sbb-title>
  A brief description.
  <sbb-secondary-button-link href="#">Read more</sbb-secondary-button-link>
</sbb-teaser-static>
```

## API (web components)

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