Paginator

The paginator divides a logically sorted collection into pages, so users can navigate and mentally orient within the set.

Overview

The paginator component enables navigation through large collections of items by breaking content into manageable pages. It is typically used with tables, lists, and card collections to help users navigate datasets while maintaining their orientation within the results, but can be used in any context where pagination of content is desired.

Pagination works best when records are sorted in a logical way, allowing users to mentally bookmark their location in an ordered result set.

Usage

forge-paginator navigates a total-item collection through pageIndex, pageSize, pageSizeOptions, and firstLast/first jump buttons, plus an alternative compact layout. Pair it with a table or list whose data is sorted in a logical order, so a user can jump to a page or mentally orient within the set. For casual browsing or discovery, infinite scroll fits better than pagination.

Rules

Let users choose how many records to show per page via pageSizeOptions.

Default to fewer records per page for a large data set if load time is a concern.

Return a user to their previous page position when they navigate back from a detail view.

Display the paginator below the content it paginates, never fixed in place or covering content.

Don't

Don't use pagination for casual browsing or discovery — infinite scroll fits that better.

Don't fix the paginator's position so it overlaps the content above it.

Don't omit page-size control on a data set large enough that users would want to adjust it.

Don't use pagination when datasets are small and don't require breaking into pages.

Don't use when there is real-time content where new items are frequently added at the top.

Basic usage

Set total to the full item count; the paginator computes page count from pageSize.

A paginator for a 100-item collection.

<forge-paginator total="100">
</forge-paginator>

Alternative layout

Set alternative for a more compact layout that swaps the page-size select and range label for a simpler page-count label — useful in tight spaces.

The compact alternative layout, better suited to tight spaces.

<forge-paginator page-size="1" total="10" alternative>
</forge-paginator>

Paginators provide navigation controls for dividing content across multiple pages. Typically used alongside data tables or lists.

import "@tylertech/forge/paginator";

Properties

Property	Attribute	Type	Default	Description
`pageIndex`	`page-index`	`unknown`	`0`	The zero-based page index.
`pageSize`	`page-size`	`unknown`	`25`	Number of items to display on a page.
`offset`	`offset`	`unknown`	`0`	Sets page index by providing the number of items to skip. The getter for this property returns the number of items to skip.
`total`	`total`	`unknown`	`0`	The total number of items to be paginated.
`pageSizeOptions`	`page-size-options`	`number[]`	`[5, 15, 25, 50, 100]`	The set of provided page size options to display to the user.
`label`	`label`	`unknown`	`"Rows per page:"`	A label for the paginator.
`firstLast`	`first-last`	`boolean`	`false`	Whether to show the first page and last page buttons.
`first`	`first`	`boolean`	`false`	Whether to show the first page button.
`disabled`	`disabled`	`boolean`	`false`	Whether the paginator is disabled.
`alternative`	`alternative`	`boolean`	`false`	Whether to use the alternative range label slot.
`rangeLabelCallback`	—	`PaginatorRangeLabelBuilder`	—	A callback function to build the range label dynamically.

Events

Name	Type	Description
`forge-paginator-change`	`CustomEvent<IPaginatorChangeEventData>`	Dispatched when the paginator state changes. Cancelable.

Slots

Name	Description
`label`	Overrides the label text when in the default variant.
`range-label`	Overrides the default range label with a custom label when in the default variant.
`alternative-range-label`	Overrides the default range label with a custom label when in the `alternative` variant.
`first-page-tooltip`	Overrides the default tooltip for the first page button.
`last-page-tooltip`	Overrides the default tooltip for the last page button.
`previous-page-tooltip`	Overrides the default tooltip for the previous page button.
`next-page-tooltip`	Overrides the default tooltip for the next page button.

CSS Parts

Name	Description
`::part(root)`	The root container element.
`::part(container)`	The label/page-size/range-label container.
`::part(label)`	The label container.
`::part(page-size-options)`	The page size `forge-select` element.
`::part(range-label)`	The range label container.
`::part(alternative-range-label)`	The alternative range label container.
`::part(actions)`	The actions container for the nav buttons.
`::part(first-page-button)`	The first page icon-button.
`::part(first-page-icon)`	The first page icon.
`::part(previous-page-button)`	The previous page icon-button.
`::part(previous-page-button-icon)`	The previous page icon.
`::part(next-page-button)`	The next page icon-button.
`::part(next-page-icon)`	The next page icon.
`::part(last-page-button)`	The last page icon-button.
`::part(last-page-icon)`	The last page icon.

Methods

Name	Returns	Description
`focus(options)`	`void`	Sets focus to the first focusable element within the paginator.
`goToFirstPage()`	`void`	Navigates to the first page.
`goToPreviousPage()`	`void`	Navigates to the previous page.
`goToNextPage()`	`void`	Navigates to the next page.
`goToLastPage()`	`void`	Navigates to the last page.
`canGoToFirstPage()`		Checks if navigation to the first page is possible.
`canGoToPreviousPage()`		Checks if navigation to the previous page is possible.
`canGoToNextPage()`		Checks if navigation to the next page is possible.
`canGoToLastPage()`		Checks if navigation to the last page is possible.

Accessibility documentation coming soon.