ba-pagination

This component for navigating large sets of content

GitHub

Storybook

Live Demo

<ba-pagination
  total="20"
  current="1"
  show-items-per-page
></ba-pagination>

Guidelines

Use when content is split across multiple pages and the user benefits from knowing their position within the full set. For example, search results, data tables, or content listings.Do not use when all items are visible on a single page.

Different variants are shown depending on how many total pages are needed and what page the user is currently on.

Full range

The full range of pages is shown when the total number is 7 pages or less

Start overflow

Used when there are more than 7 pages and the user is near the beginning of the set. The first four pages are shown, followed by an ellipsis, then the last page. The previous arrow is hidden.

Pagination with overflow for the last pages

Middle overflow

Used when the user is far enough from both ends that truncation is needed on both sides. The first and last pages are always anchored. The current page and one page either side are shown in the centre.

Pagination with overflows either side of the current page

End overflow

The mirror of Overflow start. Used when the user is near the end of the set. The first page is shown, followed by an ellipsis, then the last four pages. The next arrow is hidden.

Pagination with overflow for the start pages

Compact

This version is used on mobile. All pages are contained in the dropdown.

Code

Properties and Attributes

Property	Attribute	Description	Type	Default
`baseUrl`	`base-url`	The base url to use for each page link. The page number will be appended to this url as a query parameter, e.g. `?page=2`	`string \| undefined`	`window.location.href`
`current`(required)	`current`	The current page number	`number`	`undefined`
`currentItemsPerPage`	`current-items-per-page`	The current number of items per page	`string \| undefined`	`undefined`
`showItemsPerPage`	`show-items-per-page`	Whether to show the items per page dropdown	`boolean \| undefined`	`false`
`total`(required)	`total`	The total number of pages	`number`	`undefined`

Events

Event	Description	Type
`baPaginationLinkClick`	Emitted when the internal link is clicked. For use with single-page app (SPA) routing so that link clicks can be handled to avoid a full page load.	`CustomEvent<PaginationLinkClickEventDetail>`
`baPaginationItemsPerPageChange`	Emitted when the items per page value has changed.	`CustomEvent<any>`

Slots

No slotted content available for this component.

Permitted ARIA roles

None

Usage

Basic usage

A basic pagination component showing the user on the first page of a total of 7 pages

<ba-pagination total="20" current="1"></ba-pagination>

A select dropdown with the ability to change how many items per page to show

<ba-pagination total="20" current="1" show-items-per-page></ba-pagination>

Usage in a single page application

baPaginationLinkClick and baPaginationItemsPerPageChange events being used in a single page application

<ba-pagination total="20" current="1" show-items-per-page></ba-pagination>

<script>
  pagination.addEventListener("baPaginationLinkClick", (event) => {
    event.detail.preventDefault();

    // Before custom SPA routing
  });

  pagination.addEventListener("baPaginationItemsPerPageChange", (event) => {
    event.detail.preventDefault();

    // Before custom SPA routing
  });
</script>