# Title

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/title/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-title--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/title/overview (API: https://lyne-angular.app.sbb.ch/angular/components/title/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=7491-64
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/title

## Elements

- `sbb-title`

## Overview

### What does the component do?
The title component displays headings in six hierarchy levels (H1–H6) and structures content clearly.

### When should the component be used?
* For the main heading of a page or section.
* To represent the structure and hierarchy of content.

### Rules.
* The level (`level`) follows the structure of the page, not the desired size. Do not skip levels; use only one H1 per page.
* If the appearance differs from the semantics, set the visual size with `visualLevel`.
* Use the negative variant on dark backgrounds.
* Avoid too many titles on a page.

## Implementation (web components)

The `<sbb-title>` is a component which renders a heading element according to the provided `level` (default: `1`).

```html
<sbb-title>Hello</sbb-title>
```

### Style

In scenarios where the visual representation needs to be different from the semantic meaning of the title level,
it is possible to use the `visualLevel` property.
The available values for both `level` and `visualLevel` are the numbers from 1 to 6 (`h1` to `h6`).

```html
<sbb-title level="3" visual-level="4">Hi!</sbb-title>
```

The component has a `negative` variant which can be set with the self-named property.

```html
<sbb-title negative>Negative</sbb-title>
```

As a default the `<sbb-title>` contains spacing on top and bottom on the host.
This can be removed or customized via simple CSS rules.

### Lean theme

With the `lean` theme, the title is given smaller sizes and spacings.

## API (web components)

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