Pagination

Navigate a collection with controlled page and page-size choices.

Category: Data and hierarchy
Import: @neural-ui/core/pagination
Selector: neu-pagination

import { NeuPaginationComponent } from '@neural-ui/core/pagination';

Usage

page is one-based. Provide total and pageSize, accept pageChange and use the applied values to fetch or slice the data. pageSizeOptions adds an optional selector. Accept pageSizeChange and pageChange: changing the size proposes a page that keeps the first visible record in view. maxVisible limits the numbered range, with first/last pages and ellipses for longer collections.

Examples

Try the behavior and open Code for the implementation.

Order 1
Order 2
Order 3
Order 4
Order 5
Order 6
Order 7
Order 8
Order 9
Order 10

The application slices the collection; Pagination only proposes page changes.

Try and configure

Change the options and try the result. The generated template follows your configuration; Code contains the complete executable source.

Current page: 1 · Total: 84

Total items

Page size

Visible page buttons

Page size accessible name

Page size selector

<neu-pagination
  [page]="page()"
  [total]="84"
  [pageSize]="pageSize()"
  [maxVisible]="5"
  [pageSizeOptions]="[5,10,20]"
  pageSizeAriaLabel="Items per page"
  (pageChange)="page.set($event)"
  (pageSizeChange)="changeSize($event)"
/>

State and data for this configuration

These values match the current preview. Complete handlers, Core imports and templates are in Source.

import { signal } from '@angular/core';

export const page = signal(1);

export const pageSize = signal(10);

Data and content

pageChange and pageSizeChange are proposals, not data loading. Keep one applied page and pageSize in the application. Pagination does not mutate or fetch your records.

Accessibility and keyboard

Pagination is a named navigation landmark. The current page uses aria-current="page". Previous/next actions are disabled at the boundaries. The optional size selector has its own accessible name. Buttons support Tab, Enter and Space.

Key	Action
`Tab`	Move through available page controls and the optional page-size selector.
`Enter`	Activate the focused page button; unavailable boundary actions remain disabled.
`Space`	Activate the focused page button; unavailable boundary actions remain disabled.
`ArrowUp / ArrowDown`	In an open page-size selector, move through its options.
`Escape`	Close an open page-size selector.

API

Inputs and Outputs match the pinned package. Named types link to their definitions; each supported Template has an executable example.

Inputs

Configure the component with [property]="value". Your application supplies these values; the component does not replace the state you pass in.

Name	Type	Default	Template binding	Description
`maxVisible`	`number`	`7`	`[maxVisible]`	Maximum numbered range, excluding previous/next; use at least 3.
`page`	`number`	`1`	`[page]`	Applied page number, starting at 1.
`pageSize`	`number`	`10`	`[pageSize]`	Applied positive number of records per page.
`pageSizeAriaLabel`	`string`	`'Items per page'`	`[pageSizeAriaLabel]`	Accessible name of the optional size selector.
`pageSizeOptions`	`readonly number[]`	`[]`	`[pageSizeOptions]`	Positive size choices; an empty array hides the selector.
`total`	`number`	`0`	`[total]`	Total record count, not the number of pages.

Outputs

Listen to an event with (event)="handler($event)". The table explains the data your handler receives and how to use it.

Name	Payload	Template binding	Description
`pageChange`	`number`	`(pageChange)="onPageChange($event)"`	Proposes a clamped one-based page.
`pageSizeChange`	`number`	`(pageSizeChange)="onPageSizeChange($event)"`	Proposes the next page size.

Templates

ng-content projects content into the component. TemplateRef inputs receive a template; ng-template directives identify templates with a typed context. A directive shared by an entrypoint is not necessarily a slot of this component.

This component does not expose content projection or public customization templates.

Styles and tokens

Use public tokens for spacing, surface, text and focus. Check projected content and controls in both themes and at narrow widths.

Specific tokens

This component uses shared theme tokens rather than dedicated component hooks.

Shared tokens used

Override these on a local wrapper to affect this example. An override on :root affects other components that use the same token.

Token	Purpose here	Other impact	Default / fallback
`--neu-border`	Normal control and cell borders	Shared by other Core consumers; scope the override.	`rgba(15, 23, 42, 0.08)`
`--neu-border-hover`	Control borders on hover	Shared by other Core consumers; scope the override.	`rgba(15, 23, 42, 0.16)`
`--neu-primary`	Brand color for active controls and emphasis	Shared by other Core consumers; scope the override.	`#007aff`
`--neu-primary-dark`	Dark brand shade; outline and ghost Button text in the light theme	Shared by other Core consumers; scope the override.	`#005fcc`
`--neu-primary-fg`	Foreground drawn over the primary background	Shared by other Core consumers; scope the override.	`#ffffff`
`--neu-primary-solid`	Solid brand action background	Shared by other Core consumers; scope the override.	`#006ee6`
`--neu-primary-solid-fg`	Foreground of solid brand actions	Shared by other Core consumers; scope the override.	`#ffffff`
`--neu-primary-solid-hover`	Hover background of solid brand actions	Shared by other Core consumers; scope the override.	`#005fcc`