Paginator
Controlled collection navigation with compact page ranges, page-size selection, and localization callbacks.
- Selector
- ui-paginator
- Package
- @ngnova/ui/paginator
Import
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.
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.
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.
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.
| Name | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Controlled one-based current page. |
pageSize | number | 10 | Controlled number of items per page. |
totalItems | number | 0 | Total collection size used for page and range calculations. |
pageSizeOptions | readonly number[] | [] | Available page sizes; an empty array hides the selector. |
siblingCount | number | 1 | Visible numbered pages on either side of the current page. |
showFirstLast | boolean | true | Shows first-page and last-page navigation controls. |
disabled | boolean | false | Disables page and page-size changes. |
ariaLabel | string | 'Pagination' | Accessible name for the navigation landmark. |
itemsPerPageLabel | string | 'Items per page' | Localized visible label for page size. |
firstPageAriaLabel | string | 'First page' | Localized first-page control name. |
previousPageAriaLabel | string | 'Previous page' | Localized previous-page control name. |
nextPageAriaLabel | string | 'Next page' | Localized next-page control name. |
lastPageAriaLabel | string | 'Last page' | Localized last-page control name. |
getPageAriaLabel | (page: number) => string | Page {number} | Creates localized accessible names for numbered buttons. |
getRangeLabel | (start: number, end: number, total: number) => string | {start}–{end} of {total} | Creates the localized live collection range. |
Outputs
pageChange number Requests a new controlled one-based page.
pageSizeChange number Requests a new controlled page size.
| Name | Type | Description |
|---|---|---|
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.