gog-paginator

Paginator

Page-number controls with no notion of rows or columns, so they drop into a table, an accordion, a plain list, or anything else you page through. Hand it a row count and it works out the pages itself; hand it a page count and it uses that.

Overview

Import the component and drop it into a template.

import { PaginatorComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [PaginatorComponent],
})

page is a two-way bindable model — [(page)]="mySignal" — and totalPages is the only other thing the paginator needs. By default it shows a fixed, centered window of page buttons that slides as you navigate.

<gog-paginator [(page)]="page" [totalPages]="totalPages()" />

Page 1 of 20

Paging a row count — `totalRecords`21.4.0

Usually you know how many rows there are, not how many pages. Give the paginator totalRecords and it derives the page count from pageSize itself — which removes the computed(() => Math.ceil(total / size)) you would otherwise write and keep in sync with the rows-per-page select.

Showing 1–10 of 137

<gog-paginator
  [(page)]="page"
  [(pageSize)]="pageSize"
  [totalRecords]="items().length"
  [showPageSizeSelect]="true"
  [pageSizeOptions]="[10, 20, 50]"
/>

totalPages still works and is the right input when a server tells you a page count directly; totalRecords wins when both are set.

The rows-per-page select is off by default — turn it on per instance, or app-wide through GOG_CONFIG.paginator (showPageSizeSelect, pageSizeOptions), with GOG_CONFIG.labels.rowsPerPage for its accessible name. See Global Configuration.

Changing the size always returns to page 1: "page 5" of 10-row pages is not "page 5" of 50-row ones, so clamping alone would leave the user somewhere they never asked to be.

pageSize being a model on both the paginator and the table is what makes the two connect with no go-between signal — the table binds its own model straight to the paginator's, and the select writes back through it.

Examples

Range mode: window (default)

Keeps exactly visiblePages buttons on screen, centered on the current page. showFirstPage / showLastPage pin the first/last page with a "…" once it scrolls out of the window — click through to page 10+ to see it.

Page 10 of 20

<gog-paginator
  [(page)]="page"
  [totalPages]="totalPages()"
  [visiblePages]="5"
  [showFirstPage]="true"
  [showLastPage]="true"
/>

Range mode: ellipsis

The original behavior, kept as an opt-in for consumers already built around that look (like gog-table): first and last page always pinned, siblingCount pages kept around the current one, with a "…" filling the gap.

Page 10 of 20

<gog-paginator
  [(page)]="page"
  [totalPages]="totalPages()"
  rangeMode="ellipsis"
  [siblingCount]="1"
/>

Sizes

Five size steps, from xsm to slg.

xsm

slg

@for (sizeOption of sizes; track sizeOption) {
  <gog-paginator [totalPages]="5" [page]="page()" [size]="sizeOption" />
}

Full width

Full width of its container by default — the dashed outline below is the container, not the paginator, so you can see the box claims the full row even though the buttons don't fill it. [fullWidth]="false" shrinks the box to fit the buttons instead.

fullWidth: true (default)

fullWidth: false

<gog-paginator [totalPages]="5" [page]="2" />
<gog-paginator [totalPages]="5" [page]="2" [fullWidth]="false" />

Disabled

Freezes every control — useful while the page it navigates is itself loading.

<gog-paginator [(page)]="page" [totalPages]="8" [disabled]="true" />

Applied to a plain list

No table, no rows — just an array sliced by hand using page and a page size the consumer owns.

Apple
Banana
Cherry
Date

<ul>
  @for (item of visibleItems(); track item) {
    <li>{{ item }}</li>
  }
</ul>
<gog-paginator [(page)]="page" [totalPages]="totalPages()" />

API Reference

Inputs

Name	Type	Default	Description
`page`	`number (model)`	`1`	1-based current page. Two-way bindable: [(page)]="myPageSignal". Self-clamps to [1, totalPages] whenever totalPages shrinks below it.
`totalRecords`21.4.0	`number \| null`	`null`	How many rows exist. Given this, the paginator derives the page count from pageSize itself — which is what removes the Math.ceil(total / size) a consumer otherwise writes and keeps in sync. Wins over totalPages when both are set.
`pageSize`21.4.0	`number (model)`	`10`	Rows per page, two-way bindable. Changing it always returns to page 1 — "page 5" of 10-row pages is not "page 5" of 50-row ones.
`showPageSizeSelect`21.4.0	`boolean \| undefined`	`false`	Whether the rows-per-page select renders at all. Also settable app-wide via GOG_CONFIG.paginator.
`pageSizeOptions`21.4.0	`number[] \| undefined`	`[10, 20, 30, 40, 50]`	The choices that select offers. Also settable app-wide via GOG_CONFIG.paginator.
`totalPages`	`number`	`1`	Total number of pages. Still the right input when a server hands you a page count directly.
`rangeMode`	`'window' \| 'ellipsis'`	`'window'`	'window': a fixed number of page buttons (visiblePages) that slides to keep the current page centered, clamped at the edges — no ellipsis, no pinned boundaries unless showFirstPage/showLastPage ask for them. 'ellipsis': first and last page are always pinned, with siblingCount pages kept around the current one and a "…" filling the gap.
`visiblePages`	`number`	`5`	rangeMode="window" only: how many page number buttons stay visible at once.
`showFirstPage`	`boolean`	`false`	rangeMode="window" only: always keep page 1 reachable, with a "…" if it is not adjacent.
`showLastPage`	`boolean`	`false`	rangeMode="window" only: always keep the last page reachable, with a "…" if it is not adjacent.
`siblingCount`	`number`	`2`	rangeMode="ellipsis" only: how many page numbers to keep on each side of the current page.
`size`	`'xsm' \| 'sm' \| 'md' \| 'lg' \| 'slg'`	`'sm'`	Button height, padding, and font size.
`fullWidth`	`boolean`	`true`	Fills its container by default. Set false to shrink to fit the page buttons instead.
`disabled`	`boolean`	`false`	Freezes every control.
`ariaLabel`	`string`	`'Pagination'`	Accessible name for the navigation landmark. Its default now comes from GOG_CONFIG.labels.pagination.

Styling Tokens

Every CSS custom property the paginator paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

Token	Description
`--gog-paginator-gap`	Gap between page controls.
`--gog-paginator-ellipsis-color / -ellipsis-font-size`	The "…" truncation marker.