Primitives

Pagination

The Pagination primitives provide a set of directives to create a pagination control. The pagination control is used to navigate through a set of data that is split into multiple pages.

import { Component, signal } from "@angular/core";
import { NgIcon, provideIcons } from "@ng-icons/core";
import {
  heroChevronDoubleLeft,
  heroChevronDoubleRight,
  heroChevronLeft,
  heroChevronRight,
} from "@ng-icons/heroicons/outline";
import {
  NgpPagination,
  NgpPaginationButton,
  NgpPaginationFirst,
  NgpPaginationLast,
  NgpPaginationNext,
  NgpPaginationPrevious,
} from "ng-primitives/pagination";

@Component({
  selector: "app-pagination",
  imports: [
    NgIcon,
    NgpPagination,
    NgpPaginationButton,
    NgpPaginationFirst,
    NgpPaginationNext,
    NgpPaginationPrevious,
    NgpPaginationLast,
  ],
  providers: [
    provideIcons({
      heroChevronDoubleLeft,
      heroChevronDoubleRight,
      heroChevronLeft,
      heroChevronRight,
    }),
  ],
  template: `
    <nav
      [(ngpPaginationPage)]="page"
      ngpPagination
      ngpPaginationPageCount="5"
      aria-label="Pagination Navigation"
    >
      <ul>
        <li>
          <button ngpPaginationFirst aria-label="First Page">
            <ng-icon name="heroChevronDoubleLeft" />
          </button>
        </li>

        <li>
          <button ngpPaginationPrevious aria-label="Previous Page">
            <ng-icon name="heroChevronLeft" />
          </button>
        </li>

        <li>
          <button
            ngpPaginationButton
            ngpPaginationButtonPage="1"
            aria-label="Page 1"
          >
            1
          </button>
        </li>
        <li>
          <button
            ngpPaginationButton
            ngpPaginationButtonPage="2"
            aria-label="Page 2"
          >
            2
          </button>
        </li>
        <li>
          <button
            ngpPaginationButton
            ngpPaginationButtonPage="3"
            aria-label="Page 3"
          >
            3
          </button>
        </li>
        <li>
          <button
            ngpPaginationButton
            ngpPaginationButtonPage="4"
            aria-label="Page 4"
          >
            4
          </button>
        </li>
        <li>
          <button
            ngpPaginationButton
            ngpPaginationButtonPage="5"
            aria-label="Page 5"
          >
            5
          </button>
        </li>

        <li>
          <button ngpPaginationNext aria-label="Next Page">
            <ng-icon name="heroChevronRight" />
          </button>
        </li>

        <li>
          <button ngpPaginationLast aria-label="Last Page">
            <ng-icon name="heroChevronDoubleRight" />
          </button>
        </li>
      </ul>
    </nav>
  `,
  styles: `
    :host {
      display: contents;
    }

    ul {
      display: flex;
      align-items: center;
      column-gap: 0.5rem;
    }

    [ngpPaginationFirst],
    [ngpPaginationPrevious],
    [ngpPaginationButton],
    [ngpPaginationNext],
    [ngpPaginationLast] {
      all: unset;
      display: flex;
      justify-content: center;
      align-items: center;
      width: 2rem;
      height: 2rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      outline: none;
      font-size: 14px;
      font-weight: 500;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-button-shadow);
      cursor: pointer;
      transition: background-color 0.2s;

      &[data-hover]:not([data-disabled]):not([data-selected]) {
        background-color: var(--ngp-background-hover);
      }

      &[data-focus-visible]:not([data-disabled]) {
        outline: 2px solid var(--ngp-focus-ring);
      }

      &[data-press]:not([data-disabled]):not([data-selected]) {
        background-color: var(--ngp-background-active);
      }

      &[data-disabled] {
        color: rgb(210 210 210);
        background-color: var(--ngp-background-disabled);
        cursor: not-allowed;
        box-shadow: none;
      }

      &[data-selected] {
        background-color: var(--ngp-background-inverse);
        color: var(--ngp-text-inverse);
      }
    }
  `,
})
export default class PaginationExample {
  /**
   * The currently selected page.
   */
  readonly page = signal<number>(1);
}

Import

Import the Pagination primitives from ng-primitives/pagination.

import {
  NgpPagination,
  NgpPaginationButton,
  NgpPaginationFirst,
  NgpPaginationNext,
  NgpPaginationPrevious,
  NgpPaginationLast,
} from 'ng-primitives/pagination';

Usage

Assemble the pagination directives in your template.

<nav
  [(ngpPaginationPage)]="page"
  ngpPagination
  ngpPaginationPageCount="5"
  aria-label="Pagination Navigation"
>
  <ul>
    <li>
      <a ngpPaginationFirst aria-label="First Page">
        <ng-icon name="heroChevronDoubleLeft" />
      </a>
    </li>

    <li>
      <a ngpPaginationPrevious aria-label="Previous Page">
        <ng-icon name="heroChevronLeft" />
      </a>
    </li>

    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="1" aria-label="Page 1">1</a>
    </li>
    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="2" aria-label="Page 2">2</a>
    </li>
    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="3" aria-label="Page 3">3</a>
    </li>
    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="4" aria-label="Page 4">4</a>
    </li>
    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="5" aria-label="Page 5">5</a>
    </li>

    <li>
      <a ngpPaginationNext aria-label="Next Page">
        <ng-icon name="heroChevronRight" />
      </a>
    </li>

    <li>
      <a ngpPaginationLast aria-label="Last Page">
        <ng-icon name="heroChevronDoubleRight" />
      </a>
    </li>
  </ul>
</nav>

Reusable Component

Create a reusable component that uses the pagination directives.

import { Component } from '@angular/core';
import { Pagination } from './pagination';

@Component({
  selector: 'app-root',
  imports: [Pagination],
  template: `
    <app-pagination pageCount="5" aria-label="Pagination" />
  `,
})
export default class App {}

Schematics

Generate a reusable pagination component using the Angular CLI.

ng g ng-primitives:primitive pagination

Options

path: The path at which to create the component file.
prefix: The prefix to apply to the generated component selector.
componentSuffix: The suffix to apply to the generated component class name.
fileSuffix: The suffix to apply to the generated component file name. Defaults to component.
exampleStyles: Whether to include example styles in the generated component file. Defaults to true.

API Reference

The following directives are available to import from the ng-primitives/pagination package:

NgpPagination

The `NgpPagination` directive is used to create a pagination control.

Selector: [ngpPagination]
Exported As: ngpPagination

ngpPaginationPage

number

The currently selected page.

ngpPaginationPageCount

number

The total number of pages.

ngpPaginationDisabled

boolean

Whether the pagination is disabled.

ngpPaginationPageChange

number

The event that is fired when the page changes.

Data Attributes

The following data attributes are applied to the ngpPagination directive:

Attribute	Description	Value
`data-page`	The current page number.	`number`
`data-page-count`	The total number of pages.	`number`
`data-disabled`	Disables the pagination control.	`boolean`
`data-first-page`	Whether the current page is the first page.	`boolean`
`data-last-page`	Whether the current page is the last page.	`boolean`

NgpPaginationButton

The `NgpPaginationButton` directive is used to create a pagination button.

Selector: [ngpPaginationButton]
Exported As: ngpPaginationButton

ngpPaginationButtonPage

number

required

Define the page this button represents.

ngpPaginationButtonDisabled

boolean

Whether the button is disabled.

Data Attributes

The following data attributes are applied to the ngpPaginationButton directive:

Attribute	Description	Value
`data-page`	The page number that the button navigates to.	`number`
`data-selected`	Applied when the button is selected.	`-`
`data-hover`	Applied when the button is hovered.	`-`
`data-focus-visible`	Applied when the button is focused.	`-`
`data-press`	Applied when the button is pressed.	`-`
`data-disabled`	Disables the pagination button.	`-`

NgpPaginationFirst

The `NgpPaginationFirst` directive is used to create a pagination button that navigates to the first page.

Selector: [ngpPaginationFirst]
Exported As: ngpPaginationFirst

ngpPaginationFirstDisabled

boolean

Whether the button is disabled.

Data Attributes

The following data attributes are applied to the ngpPaginationFirst directive:

Attribute	Description
`data-first-page`	Applied when the current page is the first page.
`data-hover`	Applied when the button is hovered.
`data-focus-visible`	Applied when the button is focused.
`data-press`	Applied when the button is pressed.
`data-disabled`	Applied when the button is disabled.

NgpPaginationPrevious

The `NgpPaginationPrevious` directive is used to create a pagination button that navigates to the previous page.

Selector: [ngpPaginationPrevious]
Exported As: ngpPaginationPrevious

ngpPaginationPreviousDisabled

boolean

Whether the button is disabled.

Data Attributes

The following data attributes are applied to the ngpPaginationPrevious directive:

Attribute	Description
`data-first-page`	Applied when the current page is the first page.
`data-hover`	Applied when the button is hovered.
`data-focus-visible`	Applied when the button is focused.
`data-press`	Applied when the button is pressed.
`data-disabled`	Applied when the button is disabled.

NgpPaginationNext

The `NgpPaginationNext` directive is used to create a pagination button that navigates to the next page.

Selector: [ngpPaginationNext]
Exported As: ngpPaginationNext

ngpPaginationNextDisabled

boolean

Whether the button is disabled.

Data Attributes

The following data attributes are applied to the ngpPaginationNext directive:

Attribute	Description
`data-last-page`	Applied when the current page is the last page.
`data-hover`	Applied when the button is hovered.
`data-focus-visible`	Applied when the button is focused.
`data-press`	Applied when the button is pressed.
`data-disabled`	Applied when the button is disabled.

NgpPaginationLast

The `NgpPaginationLast` directive is used to create a pagination button that navigates to the last page.

Selector: [ngpPaginationLast]
Exported As: ngpPaginationLast

ngpPaginationLastDisabled

boolean

Whether the button is disabled.

Data Attributes

The following data attributes are applied to the ngpPaginationLast directive:

Attribute	Description
`data-last-page`	Applied when the current page is the last page.
`data-hover`	Applied when the button is hovered.
`data-focus-visible`	Applied when the button is focused.
`data-press`	Applied when the button is pressed.
`data-disabled`	Applied when the button is disabled.

Getting Started

Primitives

Interactions

Utilities

Import

Usage

Reusable Component

Schematics

Options

API Reference

NgpPagination

Data Attributes

NgpPaginationButton

Data Attributes

NgpPaginationFirst

Data Attributes

NgpPaginationPrevious

Data Attributes

NgpPaginationNext

Data Attributes

NgpPaginationLast

Data Attributes

On this page