Navigation

Pagination

Copy page

View as Markdown

Open in ChatGPT

Open in Claude

Pagination with page navigation, next and previous links.

Usage#

app.component.ts

import { WDS_PAGINATION } from '@wds/angular/pagination';

Examples#

Default#

Custom content (wds-pagination-content with items) replaces the generated buttons. With href the buttons are links, e.g. for pages rendered on the server; active marks the current page.

Show code

pagination-default.ts

import { Component } from '@angular/core';
import { WdsPaginationButtonComponent, WdsPaginationComponent, WdsPaginationContentComponent, WdsPaginationEllipsisComponent, WdsPaginationItemComponent, WdsPaginationNextComponent, WdsPaginationPreviousComponent } from '@wds/angular/pagination';

@Component({
  selector: 'app-pagination-default-demo',
  imports: [WdsPaginationComponent, WdsPaginationContentComponent, WdsPaginationItemComponent, WdsPaginationPreviousComponent, WdsPaginationButtonComponent, WdsPaginationEllipsisComponent, WdsPaginationNextComponent],
  template: `
    <wds-pagination total="10" label="Pagination">
      <wds-pagination-content>
        <wds-pagination-item>
          <wds-pagination-previous href="#" label="Previous page">Previous</wds-pagination-previous>
        </wds-pagination-item>
        <wds-pagination-item>
          <wds-pagination-button href="#" label="Page 1">1</wds-pagination-button>
        </wds-pagination-item>
        <wds-pagination-item>
          <wds-pagination-button href="#" label="Page 2" active>2</wds-pagination-button>
        </wds-pagination-item>
        <wds-pagination-item>
          <wds-pagination-button href="#" label="Page 3">3</wds-pagination-button>
        </wds-pagination-item>
        <wds-pagination-item>
          <wds-pagination-ellipsis></wds-pagination-ellipsis>
        </wds-pagination-item>
        <wds-pagination-item>
          <wds-pagination-next href="#" label="Next page">Next</wds-pagination-next>
        </wds-pagination-item>
      </wds-pagination-content>
    </wds-pagination>
  `,
})
export class PaginationDefaultDemo {}

Automatic#

Without content the element renders the pages from total itself, changes page on a click and fires wds-change. The texts it renders are built-in and currently in Polish; for another language use custom content, as in the other examples.

Page 3 of 7

Show code

pagination-automatic.ts

import { Component, signal } from '@angular/core';
import { WDS_PAGINATION } from '@wds/angular/pagination';

@Component({
  selector: 'app-pagination-automatic-demo',
  imports: [...WDS_PAGINATION],
  template: `
    <div class="flex flex-col items-center gap-3">
      <wds-pagination label="Pagination" [total]="7" [page]="page()" (wdsChange)="page.set($event.page)" />
      <p class="m-0 text-sm text-muted-foreground">Page {{ page() }} of 7</p>
    </div>
  `,
})
export class PaginationAutomaticDemo {
  protected readonly page = signal(3);
}

Simple#

simple shows the page numbers without the arrows.

Show code

pagination-simple.ts

import { Component } from '@angular/core';
import { WdsPaginationComponent } from '@wds/angular/pagination';

@Component({
  selector: 'app-pagination-simple-demo',
  imports: [WdsPaginationComponent],
  template: `
    <wds-pagination total="5" page="2" simple label="Pagination"></wds-pagination>
  `,
})
export class PaginationSimpleDemo {}

Previous and next#

Only the arrows, with the page number next to them. The text of the arrows hides on narrow screens; the label stays their accessible name.

Page 1 of 14

Show code

pagination-previous-next.ts

import { Component, signal } from '@angular/core';
import { WDS_PAGINATION } from '@wds/angular/pagination';

const TOTAL = 14;

@Component({
  selector: 'app-pagination-previous-next-demo',
  imports: [...WDS_PAGINATION],
  template: `
    <div class="flex items-center gap-4">
      <span class="text-sm whitespace-nowrap text-muted-foreground" aria-live="polite">Page {{ page() }} of {{ total }}</span>
      <wds-pagination label="Pagination" [total]="total" [page]="page()">
        <wds-pagination-content>
          <wds-pagination-item>
            <wds-pagination-previous label="Previous page" [disabled]="page() === 1" (click)="page.set(page() - 1)">Previous</wds-pagination-previous>
          </wds-pagination-item>
          <wds-pagination-item>
            <wds-pagination-next label="Next page" [disabled]="page() === total" (click)="page.set(page() + 1)">Next</wds-pagination-next>
          </wds-pagination-item>
        </wds-pagination-content>
      </wds-pagination>
    </div>
  `,
})
export class PaginationPreviousNextDemo {
  protected readonly total = TOTAL;
  protected readonly page = signal(1);
}

Rows per page#

A wds-select sets the page size, e.g. under a table. The number of pages follows from the page size, and the current page stays within range when there are fewer pages. Between the arrows a window of three pages follows the current one.

Page 1 of 14

Rows per page

100

Show code

pagination-rows-per-page.ts

import { Component, computed, signal } from '@angular/core';
import { WDS_FIELD } from '@wds/angular/field';
import { WDS_PAGINATION } from '@wds/angular/pagination';
import { WDS_SELECT } from '@wds/angular/select';

const TOTAL_ITEMS = 350;
/** Number of page buttons between the arrows. */
const VISIBLE_PAGES = 3;

@Component({
  selector: 'app-pagination-rows-per-page-demo',
  imports: [...WDS_FIELD, ...WDS_PAGINATION, ...WDS_SELECT],
  template: `
    <div class="grid w-full items-center justify-items-center gap-4 sm:grid-cols-[1fr_auto_1fr]">
      <span class="text-sm whitespace-nowrap text-muted-foreground sm:justify-self-start" aria-live="polite">
        Page {{ page() }} of {{ pages() }}
      </span>
      <wds-pagination class="w-fit" label="Pagination">
        <wds-pagination-content>
          <wds-pagination-item>
            <wds-pagination-previous label="Previous page" [disabled]="page() === 1" (click)="goTo(page() - 1)">Previous</wds-pagination-previous>
          </wds-pagination-item>
          @for (p of visiblePages(); track p) {
            <wds-pagination-item>
              <wds-pagination-button [label]="'Page ' + p" [active]="p === page()" (click)="goTo(p)">{{ p }}</wds-pagination-button>
            </wds-pagination-item>
          }
          <wds-pagination-item>
            <wds-pagination-next label="Next page" [disabled]="page() === pages()" (click)="goTo(page() + 1)">Next</wds-pagination-next>
          </wds-pagination-item>
        </wds-pagination-content>
      </wds-pagination>
      <wds-field orientation="horizontal" class="w-fit items-center sm:justify-self-end">
        <wds-field-label class="min-w-max">Rows per page</wds-field-label>
        <wds-select size="sm" class="min-w-20" [value]="perPage()" (wdsChange)="setPerPage($event.value)">
          <wds-select-item value="10">10</wds-select-item>
          <wds-select-item value="25">25</wds-select-item>
          <wds-select-item value="50">50</wds-select-item>
          <wds-select-item value="100">100</wds-select-item>
        </wds-select>
      </wds-field>
    </div>
  `,
})
export class PaginationRowsPerPageDemo {
  protected readonly perPage = signal('25');
  protected readonly page = signal(1);
  protected readonly pages = computed(() => Math.ceil(TOTAL_ITEMS / Number(this.perPage())));

  /** A window of pages around the current one, moved by the arrows. */
  protected readonly visiblePages = computed(() => {
    const count = Math.min(VISIBLE_PAGES, this.pages());
    const first = Math.min(Math.max(1, this.page() - 1), this.pages() - count + 1);
    return Array.from({ length: count }, (_, i) => first + i);
  });

  protected goTo(page: number): void {
    this.page.set(Math.min(Math.max(1, page), this.pages()));
  }

  protected setPerPage(value: string): void {
    this.perPage.set(value);
    // Fewer pages after a change: stay within range.
    this.goTo(this.page());
  }
}

API References#

wds-pagination#

Pagination: previous page, page numbers and next page. Without content it renders buttons for pages 1…total itself and changes page on selection (wds-change event). Custom content (wds-pagination-content with items) replaces the generated list; then the app handles the clicks.

Attributes

Attribute	Type	Default	Description
page	number	1	The current page (from 1).
total	number	1	Number of pages.
simple	boolean	false	Page numbers only, without arrows.
disabled	boolean	false	Disables every button.
size	WdsPaginationSize	'icon'	Size of the page buttons; the arrows get the matching text size.
label	string	'Paginacja'	Group label for screen readers.

Events

Event	Description
wds-changeCustomEvent<WdsPaginationChangeDetail>	The user selected another page.

Slots

Slot	Description
(default)	Custom pagination structure (instead of the generated one).

wds-pagination-content#

The list of pagination items (role="list").

Slots

Slot	Description
(default)	`wds-pagination-item` elements.

wds-pagination-item#

An item of the pagination list (role="listitem"): a button, an arrow or an ellipsis.

Slots

Slot	Description
(default)	Item content.

wds-pagination-button#

A page button. The active page has the outline variant and aria-current="page", the others ghost. With href it renders a link.

Attributes

Attribute	Type	Default	Description
active	boolean	false	The current page.
disabled	boolean	false	Disables the button.
size	WdsPaginationSize	'icon'	Button size.
href	string \| undefined		Page URL: the button becomes a link.
label	string \| undefined		Accessible name (e.g. "Page 3").

Slots

Slot	Description
(default)	Page number.

CSS parts (::part)

Part	Description
button	The native `<button>` or `<a>`.

wds-pagination-previous#

Previous page button: an arrow and text (hidden on narrow screens).

Attributes

Attribute	Type	Default	Description
label	string	'Poprzednia strona'	Accessible name.
disabled	boolean	false	Disables the button (e.g. on the first or last page).
size	WdsPaginationNavSize	'default'	Button size.
href	string \| undefined		Page URL: the button becomes a link.

Slots

Slot	Description
(default)	Text (default `Poprzednia`).

CSS parts (::part)

Part	Description
button	The native `<button>` or `<a>`.

wds-pagination-next#

Next page button: text (hidden on narrow screens) and an arrow.

Attributes

Attribute	Type	Default	Description
label	string	'Następna strona'	Accessible name.
disabled	boolean	false	Disables the button (e.g. on the first or last page).
size	WdsPaginationNavSize	'default'	Button size.
href	string \| undefined		Page URL: the button becomes a link.

Slots

Slot	Description
(default)	Text (default `Następna`).

CSS parts (::part)

Part	Description
button	The native `<button>` or `<a>`.

wds-pagination-ellipsis#

An ellipsis in place of skipped pages. Hidden from screen readers.

Accessibility#

wds-pagination has role="group" named by label (default Paginacja); the items form a list. When the pagination is the main navigation of a page, wrap it in <nav aria-label="…">.

The current page has aria-current="page". Page buttons are named by their label; in automatic mode they get fixed names in Polish (Strona 3, Ostatnia strona, 7), so for English pages render custom content with your own labels.

The arrows are named by label (default Poprzednia strona / Następna strona); their text and icon are hidden from screen readers. The ellipsis is hidden too.

Keyboard support#

Key	Function
Tab	Moves focus to the next page button or arrow. Disabled arrows are skipped.
Enter	Opens the page (button or link).
Space	Opens the page of a button (links open only with Enter).

Usage#

Examples#

Default#

Automatic#

Simple#

Previous and next#

Rows per page#

API References#

wds-pagination#

Attributes

Events

Slots

wds-pagination-content#

Slots

wds-pagination-item#

Slots

wds-pagination-button#

Attributes

Slots

CSS parts (::part)

wds-pagination-previous#

Attributes

Slots

CSS parts (::part)

wds-pagination-next#

Attributes

Slots

CSS parts (::part)

wds-pagination-ellipsis#

Accessibility#

Screen reader#

Keyboard support#