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 model — [(page)]="mySignal" — and totalPages is the only other thing the paginator needs. By default it shows a fixed, centred window of page buttons that slides as you navigate.
page 1 of 12
<gog-paginator [(page)]="page" [totalPages]="12" />
<p>page {{ page() }} of 12</p>Examples
States
On the first page "previous" is disabled, on the last "next". disabled freezes every control — useful while the page it navigates is itself loading. Hover, focus and press are the buttons' own and are live.
<!-- The step buttons disable themselves at the edges. -->
<div>
<span>[page]="1"</span>
<gog-paginator [totalPages]="5" [page]="1" [fullWidth]="false" />
</div>
<div>
<span>[page]="3"</span>
<gog-paginator [totalPages]="5" [page]="3" [fullWidth]="false" />
</div>
<div>
<span>[page]="5"</span>
<gog-paginator [totalPages]="5" [page]="5" [fullWidth]="false" />
</div>
<div>
<span>disabled</span>
<gog-paginator [totalPages]="5" [page]="3" [fullWidth]="false" disabled />
</div>Range modes
window (the default) keeps visiblePages buttons and slides them to centre the current page, clamped at the edges; showFirstPage and showLastPage pin the ends with a "…" between. ellipsis always pins the first and last page and keeps siblingCount pages either side of the current one — the look gog-table uses.
<!-- Twenty pages each, starting on page 10: click towards either end. -->
<div>
<span>window (default)</span>
<gog-paginator [(page)]="windowPage" [totalPages]="20" [fullWidth]="false" />
</div>
<div>
<span>window, pinned ends</span>
<gog-paginator
[(page)]="pinnedPage"
[totalPages]="20"
showFirstPage
showLastPage
[fullWidth]="false"
/>
</div>
<div>
<span>[visiblePages]="3"</span>
<gog-paginator [(page)]="threePage" [totalPages]="20" [visiblePages]="3" [fullWidth]="false" />
</div>
<div>
<span>ellipsis</span>
<gog-paginator
[(page)]="ellipsisPage"
[totalPages]="20"
rangeMode="ellipsis"
[fullWidth]="false"
/>
</div>
<div>
<span>ellipsis, [siblingCount]="1"</span>
<gog-paginator
[(page)]="siblingPage"
[totalPages]="20"
rangeMode="ellipsis"
[siblingCount]="1"
[fullWidth]="false"
/>
</div>Paging a row count — totalRecords
Usually you know how many rows there are, not how many pages. With totalRecords the paginator derives the page count from pageSize itself, so nothing is recomputed when the rows-per-page select changes it — and changing it returns to page 1, the only position that means the same thing at every size. totalPages is still right when a server reports a page count; totalRecords wins when both are set. The select is off by default. pageSize is a model here and on the table, which is what lets the two bind straight to each other.
- Person 1
- Person 2
- Person 3
- Person 4
- Person 5
page: 1 · pageSize: 5 · totalRecords: 47
<div>
<ol [start]="(page() - 1) * pageSize() + 1">
@for (person of visiblePeople(); track person) {
<li>{{ person }}</li>
}
</ol>
</div>
<!-- totalRecords: the paginator counts pages from pageSize itself. -->
<gog-paginator
[(page)]="page"
[(pageSize)]="pageSize"
[totalRecords]="people.length"
showPageSizeSelect
[pageSizeOptions]="[5, 10, 20]"
/>
<p>page: {{ page() }} · pageSize: {{ pageSize() }} · totalRecords: {{ people.length }}</p>A page count that shrinks under the current page
The paginator is on page 8 of 8. Drop the total to 3 and it writes page 3 back through page rather than showing a page that does not exist.
page: 8 · totalPages: 8
<div>
<gog-button variant="outline" size="sm" (gogClick)="totalPages.set(3)">totalPages = 3</gog-button>
<gog-button variant="outline" size="sm" (gogClick)="reset()">Reset to 8 of 8</gog-button>
</div>
<!-- A page past the new end is written back through [(page)]. -->
<gog-paginator [(page)]="page" [totalPages]="totalPages()" [fullWidth]="false" />
<p>page: {{ page() }} · totalPages: {{ totalPages() }}</p>Full width
On by default: the paginator takes its container's width — the dashed box here. [fullWidth]="false" shrinks it to its buttons.
<gog-paginator [totalPages]="5" [page]="2" />
<gog-paginator [totalPages]="5" [page]="2" [fullWidth]="false" />App-wide defaults — GOG_CONFIG
The navigation's name and the button labels come from GOG_CONFIG.labels — pagination, previousPage, nextPage, rowsPerPage, and page, a function (page, isCurrent) => string that names each number button. Whether the rows-per-page select shows, and its choices, come from GOG_CONFIG.paginator. In an app the provider goes in app.config.ts — see Global Configuration.
<!-- No inputs beyond its pages: the labels and the select come from the config. -->
<gog-paginator [(page)]="page" [(pageSize)]="pageSize" [totalRecords]="60" [fullWidth]="false" />Accessibility
A navigation landmark of real buttons, each named for where it goes.
- Landmark — a
<nav>named byariaLabel, orGOG_CONFIG.labels.pagination. - Names — the page numbers are "Go to page N"; the current one is "Page N" with
aria-current="page"21.15.0 carrying its state. A screen reader announces that itself, so a translatedlabels.pageshould leave the "current" half out. The step buttons are named from config, since ‹ and › say nothing on their own. - Keyboard — Tab moves through the buttons and the rows-per-page select; Enter or Space presses. A disabled step button is a native
disabledbutton, out of the tab order.
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 | 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 | 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 | boolean | undefined | false | Whether the rows-per-page select renders at all. Also settable app-wide via GOG_CONFIG.paginator. |
pageSizeOptions | readonly 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. |
Outputs
| Name | Payload | Description |
|---|---|---|
pageChange | number | The new page, on a press — and when a shrinking page count pulls the page back. Comes from the page model input. |
pageSizeChange | number | The new page size, from the rows-per-page select. Comes from the pageSize model input. |
Global Configuration
Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.
GOG_CONFIG.paginator.showPageSizeSelectGOG_CONFIG.paginator.pageSizeOptionsGOG_CONFIG.labels.paginationGOG_CONFIG.labels.previousPageGOG_CONFIG.labels.nextPageGOG_CONFIG.labels.pageGOG_CONFIG.labels.rowsPerPage
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. |