Component v1.1.0 Foundations

Paginator

Controlled collection navigation with compact page ranges, page-size selection, and localization callbacks.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-paginator
Package
@ngnova/ui/paginator

Import

Standalone Tailwind v4
import { UiPaginatorComponent } from '@ngnova/ui/paginator';

Usage & variants

Live examples use the public ui-paginator API, paired with the exact snippet a product team would paste into an Angular app.

API Reference

Release results pagination

Controlled collection navigation with compact page ranges, page-size selection, and localization callbacks.

Production guidance

Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.

When to use

Use for server-side or client-side collections where users need stable pages and range context.

Watch for

Page, page size, total count, and sibling count are normalized without mutating consumer inputs.

Product recipes

Apply Paginator in distinct, copyable product scenarios—not just an isolated component state.

Controlled pagination

The parent owns page, page size, fetching, and URL synchronization.

Angular template ui-paginator-recipe.example.html
1
2
3
4
5
6
<ui-paginator
  [(page)]="page"
  [(pageSize)]="pageSize"
  [totalItems]="total"
  [pageSizeOptions]="[10, 25, 50]"
/>

Search results

Reset pagination when filters change and announce the current result range beside the controls.

Angular template ui-paginator-recipe.example.html
1
2
3
4
5
6
7
8
<p aria-live="polite">Showing {{ rangeStart }}–{{ rangeEnd }} of {{ totalResults }}</p>
<ui-paginator
  [page]="page()"
  [pageSize]="25"
  [totalItems]="totalResults"
  ariaLabel="Search result pages"
  (pageChange)="loadPage($event)"
/>

API Reference

Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.

Inputs

page 1
number

Controlled one-based current page.

pageSize 10
number

Controlled number of items per page.

totalItems 0
number

Total collection size used for page and range calculations.

pageSizeOptions []
readonly number[]

Available page sizes; an empty array hides the selector.

siblingCount 1
number

Visible numbered pages on either side of the current page.

showFirstLast true
boolean

Shows first-page and last-page navigation controls.

disabled false
boolean

Disables page and page-size changes.

ariaLabel 'Pagination'
string

Accessible name for the navigation landmark.

itemsPerPageLabel 'Items per page'
string

Localized visible label for page size.

firstPageAriaLabel 'First page'
string

Localized first-page control name.

previousPageAriaLabel 'Previous page'
string

Localized previous-page control name.

nextPageAriaLabel 'Next page'
string

Localized next-page control name.

lastPageAriaLabel 'Last page'
string

Localized last-page control name.

getPageAriaLabel Page {number}
(page: number) => string

Creates localized accessible names for numbered buttons.

getRangeLabel {start}–{end} of {total}
(start: number, end: number, total: number) => string

Creates the localized live collection range.

Outputs

pageChange number

Requests a new controlled one-based page.

pageSizeChange number

Requests a new controlled page size.

Accessibility

  • The component exposes a named navigation landmark, aria-current on the active page, named icon controls, and a polite live range.
  • Unavailable navigation and the global disabled state use native disabled controls.

Keyboard behavior

  • All controls follow native button and select keyboard behavior.
  • Tab order follows page-size, first, previous, numbered, next, and last controls without custom trapping.

Testing guidance

  • Use UiPaginatorHarness to inspect current page and range, navigate forward or to a visible page, and select page size.
  • Test first, middle, last, empty, invalid, disabled, localized, small-page-count, and ellipsis states.