Pagination

<zeno-pagination>NavigationSource

Moves between the pages of a long list.

import '@usezeno/tokens/css';
import '@usezeno/core/web-components';

Examples

Basic pagination

total is the number of items, not pages. With the default page-size of 10, 120 items give 12 pages. The element fires change when the page changes.

Page 3 is shown.

<zeno-pagination total="120" current="3"></zeno-pagination>
<p data-result>Page 3 is shown.</p>

document.querySelector('zeno-pagination').addEventListener('change', event => {
  document.querySelector('[data-result]').textContent = 'Page ' + event.detail.current + ' is shown.';
});

More pages around the current one

sibling-count is the number of page buttons on each side of the current page. The default is 1.

<zeno-pagination total="500" current="12" sibling-count="1"></zeno-pagination>
<zeno-pagination total="500" current="12" sibling-count="2"></zeno-pagination>

Sizes

<zeno-pagination total="50" size="sm"></zeno-pagination>
<zeno-pagination total="50" size="md"></zeno-pagination>
<zeno-pagination total="50" size="lg"></zeno-pagination>

Simple and compact

simple hides the page buttons and keeps Previous and Next. compact hides the words “Previous” and “Next” and keeps the arrows.

<zeno-pagination total="80" current="2" simple show-total></zeno-pagination>
<zeno-pagination total="80" current="2" compact></zeno-pagination>

Total, page size and jump to a page

show-total shows the range of items. show-size-changer adds a page size list and fires size-change. show-jumper adds a field: type a page number and press Enter.

10 items on each page.

<zeno-pagination total="240" show-total show-size-changer show-jumper></zeno-pagination>
<p data-result>10 items on each page.</p>

document.querySelector('zeno-pagination').addEventListener('size-change', event => {
  document.querySelector('[data-result]').textContent =
    event.detail.pageSize + ' items on each page.';
});

Attributes and properties

Property	Attribute	Type	Default	Description
current	current	number	1
total	total	number	1
pageSize	page-size	number	10
siblingCount	sibling-count	number	1
simple	simplereflects	boolean	false
compact	compactreflects	boolean	false
showTotal	show-totalreflects	boolean	false
showJumper	show-jumperreflects	boolean	false
showSizeChanger	show-size-changerreflects	boolean	false
size	sizereflects	'sm' | 'md' | 'lg'	'md'
pageSizes	page-sizes	array	[ 10, 20, 50, 100, ]
testId	–	string	–	Test ID for automated testing From ZenoElement.

Methods

Method	Description
goToPage(page: number): void	Go to a specific page
previousPage(): void	Go to previous page
nextPage(): void	Go to next page
focus(): void	Focus the component or its first focusable element From ZenoElement.
blur(): void	Blur the component or its focused element From ZenoElement.

Events

Event	Detail	Description
change	{ current: number; pageSize: number; total: number }	The current page changed.
size-change	{ current: number; pageSize: number; total: number }	The page size changed.

Slots

This element has no slots.

CSS parts

Part
base
ellipsis
info
jumper
jumper-input
list
nav
next
page
prev
select
size-changer

CSS custom properties

This element documents no custom properties of its own. Style it through its parts and through the tokens it reads.

The element's own source reads no tokens.

Accessibility

Keyboard

Key	What it does
Tab	Moves focus through the previous button, the page buttons, the next button, the page size list and the jump field.
EnterSpace	On a button, goes to that page.
Enter	In the jump field, goes to the typed page. A number outside the range goes to the first or last page.
ArrowUpArrowDown	In the page size list, change the page size, as in any native <select>.

Forms

This element is not a form control. It adds nothing to a form's data.

Notes

• Renders a <nav> landmark. It is named by the aria-label of the element, or “Pagination navigation” when there is none.
• Every control is a native <button>, <select> or <input>, and the page buttons are in a list.
• The button of the current page has aria-current="page". Each page button is named “Go to page” and its number.
• The previous and next buttons are named “Go to previous page” and “Go to next page”, and are disabled on the first and last page.
• With reduced motion the buttons have no transition. The element is hidden when the page is printed.

Tests and known gaps

• No tests of its own. The only check is that the element registers and renders (smoke.test.ts).
• Not checked with axe-core.
• Has no Storybook story.

23 of the 31 properties, methods, events, slots and parts above have no description in the source

• the property current
• the property total
• the property pageSize
• the property siblingCount
• the property simple
• the property compact
• the property showTotal
• the property showJumper
• the property showSizeChanger
• the property size
• the property pageSizes
• the part base
• the part ellipsis
• the part info
• the part jumper
• the part jumper-input
• the part list
• the part nav
• the part next
• the part page
• the part prev
• the part select
• the part size-changer

Known gaps:

• All text is English only and has no property: “Previous”, “Next”, “Go to page”, “of”, “/ page”, “Go to”, “Items per page” and “Page number to go to”. Only the name of the landmark can be replaced, with aria-label.
• Nothing announces the new page after a change. The page that uses the element has to do that.
• A current set from outside is not checked. With a value past the last page no button is marked as current and the next button stays enabled.
• An empty list is not handled. With total="0" and show-total the text is “1-0 of 0”, and the next button stays enabled.
• Enter in an empty jump field goes to page 1.
• A new page size can also change current, but only size-change fires. A page that listens only to change misses it.
• When page-size is not one of page-sizes, the page size list shows its first option, which is not the size in use.
• The page size list has no styles. It looks like a plain browser <select> and does not follow size.
• In simple mode nothing shows the current page unless show-total is also set.
• The gap between page numbers is three plain dots. It is not hidden from assistive technology and has no name.
• The jump field does not follow size. It is always 32px high.
• The jump field removes its focus outline and shows a border colour and a shadow instead. A shadow is not drawn in forced colours mode.
• The element gives its arrow icons the size 20, which zeno-icon does not have, so they render at the default size.