Paginator. Overview

Preview.

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.
 Usage

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.

Elements.

This component includes several elements that can be used on their own.

  • sbb-compact-paginator
  • sbb-paginator

Specification.

Open in Figma
Examples Default.
Try it out on Storybook Show HTML
With Page Size Options.
Try it out on Storybook Show HTML
Disabled.
Try it out on Storybook Show HTML
Negative.
Try it out on Storybook Show HTML
Size S.
Try it out on Storybook Show HTML
Size M.
Try it out on Storybook Show HTML
Pager Position End.
Try it out on Storybook Show HTML
Compact Default.
Try it out on Storybook Show HTML
Compact Negative.
Try it out on Storybook Show HTML
Compact Disabled.
Try it out on Storybook Show HTML
Compact Disabled Negative.
Try it out on Storybook Show HTML
Compact Size S.
Try it out on Storybook Show HTML
Compact Size M.
Try it out on Storybook Show HTML
Compact Pager Position End.
Try it out on Storybook Show HTML
Copy HTML to clipboard. Implementation

Web Components.

The web component is in the package @sbb-esta/lyne-elements.

Storybook with live examples Source code on GitHub

Documentation.

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>.

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).
<sbb-paginator length="100" page-size="20"></sbb-paginator>

By default, a sbb-mini-button-group 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):

<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.

<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.

<sbb-compact-paginator length="100" page-size="20"></sbb-compact-paginator>
States.

The component can be disabled by using the disabled property.

<sbb-paginator length="100" page-size="20" disabled></sbb-paginator>
Style.

The component has two size, named s and m.

<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.

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

Angular.

This component is also available for Angular in the package @sbb-esta/lyne-angular.

Angular overview Angular API Angular examples API

class: SbbCompactPaginatorElement, sbb-compact-paginator.

Properties.

Name Attribute Privacy Type Default Description
accessibilityNextPageLabel accessibility-next-page-label public string '' Accessibility label for the next page. Defaults to next page. Can be set for cases like a carousel, where slide or image fits better.
accessibilityPageLabel accessibility-page-label public string '' Accessibility label for the page. Defaults to page. Can be set for cases like a carousel, where slide or image fits better.
accessibilityPreviousPageLabel accessibility-previous-page-label public string '' Accessibility label for the previous page. Defaults to previous page. Can be set for cases like a carousel, where slide or image fits better.
disabled disabled public boolean false Whether the component is disabled.
length length public number 0 Total number of items.
negative negative public boolean false Negative coloring variant flag.
pageIndex page-index public number 0 Current page index.
pagerPosition pager-position public 'start' | 'end' 'start' Position of the prev/next buttons.
pageSize page-size public number 10 Number of items per page.
size size public 's' | 'm' | null null Size variant, either s (lean theme default) or m (standard theme default).

Methods.

Name Privacy Description Parameters Return Inherited From
firstPage public Move to the first page if not already there. void SbbPaginatorCommonElementMixin
hasNextPage public Whether there is a next page. boolean SbbPaginatorCommonElementMixin
hasPreviousPage public Whether there is a previous page. boolean SbbPaginatorCommonElementMixin
lastPage public Move to the last page if not already there. void SbbPaginatorCommonElementMixin
nextPage public Advances to the next page if it exists. void SbbPaginatorCommonElementMixin
numberOfPages public Calculates the current number of pages based on the length and the pageSize; value must be rounded up (e.g. length = 21 and pageSize = 10 means 3 pages). number SbbPaginatorCommonElementMixin
previousPage public Move back to the previous page if it exists. void SbbPaginatorCommonElementMixin
selectPage public Move to a specific page index. index: number void SbbPaginatorCommonElementMixin

Events.

Name Type Description Inherited From
page SbbPaginatorPageEvent The page event is dispatched when the page index, length or page size changes. SbbPaginatorCommonElementMixin

class: SbbPaginatorElement, sbb-paginator.

Properties.

Name Attribute Privacy Type Default Description
accessibilityItemsPerPageLabel accessibility-items-per-page-label public string '' Accessibility label for the items per page. Defaults to Items per page.. Can be set for cases like a carousel, where slide or image fits better.
accessibilityNextPageLabel accessibility-next-page-label public string '' Accessibility label for the next page. Defaults to next page. Can be set for cases like a carousel, where slide or image fits better.
accessibilityPageLabel accessibility-page-label public string '' Accessibility label for the page. Defaults to page. Can be set for cases like a carousel, where slide or image fits better.
accessibilityPreviousPageLabel accessibility-previous-page-label public string '' Accessibility label for the previous page. Defaults to previous page. Can be set for cases like a carousel, where slide or image fits better.
disabled disabled public boolean false Whether the component is disabled.
length length public number 0 Total number of items.
negative negative public boolean false Negative coloring variant flag.
pageIndex page-index public number 0 Current page index.
pagerPosition pager-position public 'start' | 'end' 'start' Position of the prev/next buttons: if pageSizeOptions is set, the sbb-select for the pageSize change will be positioned oppositely, with the page numbers always in the center.
pageSize page-size public number 10 Number of items per page.
pageSizeOptions page-size-options public number[] [] The available pageSize choices.
size size public 's' | 'm' | null null Size variant, either s (lean theme default) or m (standard theme default).

Methods.

Name Privacy Description Parameters Return Inherited From
firstPage public Move to the first page if not already there. void SbbPaginatorCommonElementMixin
hasNextPage public Whether there is a next page. boolean SbbPaginatorCommonElementMixin
hasPreviousPage public Whether there is a previous page. boolean SbbPaginatorCommonElementMixin
lastPage public Move to the last page if not already there. void SbbPaginatorCommonElementMixin
nextPage public Advances to the next page if it exists. void SbbPaginatorCommonElementMixin
numberOfPages public Calculates the current number of pages based on the length and the pageSize; value must be rounded up (e.g. length = 21 and pageSize = 10 means 3 pages). number SbbPaginatorCommonElementMixin
previousPage public Move back to the previous page if it exists. void SbbPaginatorCommonElementMixin
selectPage public Move to a specific page index. index: number void SbbPaginatorCommonElementMixin

Events.

Name Type Description Inherited From
page SbbPaginatorPageEvent The page event is dispatched when the page index, length or page size changes. SbbPaginatorCommonElementMixin