# Paginator

Komponente des SBB Design Systems Lyne.

- Paket: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Aufbau: mehrere eigenständige Elemente
- Kategorien: Indicator
- Status: Gestaltungsrichtlinien vollständig

## Links

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

## Elemente

- `sbb-compact-paginator`: It displays a paginator component in compact mode.
- `sbb-paginator`: It displays a paginator component.

## Übersicht

### Was macht die Komponente?
Der Paginator unterteilt grosse Inhaltsmengen, z.B. Tabellen oder Listen, in Seiten. Er zeigt die aktuelle Seite an und bietet Steuerelemente zum Wechseln. Optional können Nutzende die Anzahl Einträge pro Seite ändern. Eine kompakte Variante (Compact-Paginator) zeigt nur die aktuelle Seite und die Gesamtzahl.

### Wann soll die Komponente eingesetzt werden?
* Wenn viele Einträge in Seiten aufgeteilt werden sollen.
* Wenn eine Alternative zu unendlichem Scrollen benötigt wird.

### Regeln.
* Bei wenigen Seiten ist «Mehr laden» meist die bessere Lösung.
* Bei wenig Platz, z.B. auf kleinen Bildschirmen, wird der Compact-Paginator verwendet.
* Der Paginator braucht eine Beschriftung für Screenreader (`aria-label`), die beschreibt, was er steuert.

## Implementation (Web Components, Englisch)

The `<sbb-paginator>` is a component which provides navigation for content split across multiple pages,
e.g. a table with many rows. An alternative, more compact variant is available as [`<sbb-compact-paginator>`](#compact-paginator).

It can be controlled via the following properties:

- `length`: the total number of items being paged;
- `pageSize`: the number of items per page (default: `10`);
- `pageIndex`: the index of the current displayed page (default: `0`).

```html
<sbb-paginator length="100" page-size="20"></sbb-paginator>
```

By default, a [sbb-mini-button-group](https://lyne-elements.app.sbb.ch/?path=/docs/elements-button--docs) with two buttons is displayed,
which allows moving to the previous/next pages.
The positioning of this element relative to the page numbers is set using the `pagerPosition` property (default: `start`):

```html
<sbb-paginator length="100" page-size="20" pager-position="end"></sbb-paginator>
```

Users have the possibility to dynamically change the page size using a dropdown menu;
to do this, consumers must add the `pageSizeOptions` property, which accepts an array of number
that are set as `<sbb-option>`'s values within a `<sbb-select>`.
Consumers must be consistent, so the defined `pageSize` must be an element of the `pageSizeOptions` array.
The dropdown menu and the previous / next buttons are facing each other with the page numbers always in the center.

```html
<sbb-paginator length="100" page-size="20" page-size-options="[10, 20, 50]"></sbb-paginator>
```

#### Compact Paginator

An alternative, more compact variant with the same functionality is the `<sbb-compact-paginator>`.
In contrast to the `<sbb-paginator>`, it displays only the current page and the total number of pages
together with the `<sbb-mini-button-group>` to move to previous or next page.

```html
<sbb-compact-paginator length="100" page-size="20"></sbb-compact-paginator>
```

### States

The component can be disabled by using the `disabled` property.

```html
<sbb-paginator length="100" page-size="20" disabled></sbb-paginator>
```

### Style

The component has two `size`, named `s` and `m`.

```html
<sbb-paginator length="100" page-size="20" size="s"></sbb-paginator>
```

### Events

Consumers can listen to the `page` event on the `<sbb-paginator>` component to intercept the page change event.
The `event` contains both the information about the `pageIndex` and the `previousPageIndex`,
as well as the `length` and the `pageSize`.

### Accessibility

The component has `role="group"` to semantically group its child controls;
consumers should add an appropriate `aria-label` attribute with a text
that describes the content controlled by the paginator.

```html
<sbb-paginator aria-label="Select page" length="100" page-size="20"></sbb-paginator>
```

## API (Web Components, Englisch)

Vollständige API-Tabellen (Attribute, Events, Slots, CSS-Eigenschaften): https://digital.sbb.ch/de/design-system/lyne/components/paginator/api.md