# Paginator

Component of the SBB design system Lyne.

- Package: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Structure: several elements that can be used on their own
- Categories: Indicator
- Status: Design guidelines complete

## Links

- Page on digital.sbb.ch: https://digital.sbb.ch/en/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

## Elements

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

## Overview

### What does the component do?
The paginator divides large amounts of content, e.g. tables or lists, into pages. It shows the current page and provides controls to switch pages. Optionally, users can change the number of entries per page. A compact variant (compact paginator) shows only the current page and the total.

### When should the component be used?
* When many entries should be split into pages.
* When an alternative to infinite scrolling is needed.

### Rules.
* For few pages, "Load more" is usually the better solution.
* When space is limited, e.g. on small screens, use the compact paginator.
* The paginator needs a label for screen readers (`aria-label`) that describes what it controls.

## Implementation (web components)

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)

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