<c-pagination>
A page navigation bar for a list split into pages: previous and next buttons around a window of page buttons, with a page-size menu and the range of items shown.
Usage
Its value is one object holding the item count, the current page and the page size. Bind it with v-model, or set it and listen for change. Objects have no attribute form, so value is a DOM property: v-model or :value in Vue, the React wrapper's value, property assignment in plain JavaScript.
<c-pagination v-model="pagination" />
When to use
- Paging through a list or a table you render yourself — a
c-table, a list of cards — that would be too long to show at once. - Not with
c-data-table: it renders its own pagination once itspage-sizeis set.
Value
value is a CPaginationOptions object:
itemCount(required) — the number of items to page through. The buttons, previous and next included, appear only while it is above 0.page— the current page, counting from 1. Default 1.pageSize— items per page. Default 25.pageSizes— the sizes the page-size menu offers. Default[5, 25, 50, 100].totalVisible— the most page buttons shown at once, ellipses included. Default 7. With more pages than that, the first and last page stay in view and an ellipsis stands for the pages left out.
Each pick — a page button, previous, next, a page size — emits a new object: your fields, the picked page and pageSize, and startFrom and endTo, the 0-based indices of the page's first and last item. A new page size returns to page 1. startFrom and endTo are set only on emitted values; on a short last page endTo is the last item, so items.slice(startFrom, endTo + 1) gives the page's items.
The pagination never writes into your object, and setting value emits nothing: it only moves the controls to the new value. A new object does that even when its fields are unchanged, so write the emitted value back (as v-model does) or keep the object stable between renders. An object literal re-created on every React render resets the page each time.
Events
c-pagination is a value control: each pick fires change with the new value, along with update:value carrying the same value and a bubbling input. In Vue, v-model rides these; in React, onChange receives the value as event.detail.
Layout
hide-detailshides the page-size menu and the range text, leaving the buttons.hide-rangehides only the range text.simpledrops the page buttons and moves previous and next to the bar's end; the range text is then the only sign of position. Withhide-details simple, previous and next are all that remain.size="small"renders compact buttons.
While both fit, the page-size menu and the range text share a row, the range at its right edge; in a narrow container the range moves under the menu.
Texts
Every built-in string can be replaced through texts, merged key by key over the English defaults: pagination (the landmark's name, "Pagination"), pageSize (the menu's label, "Items per page:"), previousPage and nextPage (the arrow buttons' names), page (a page button's name, from the page and the page count: "page 3 of 10") and range (the range text, from the first and last item, counting from 1, and the item count: "11 - 20 of 96 items"). Some keys are functions, so bind the object as a DOM property:
<c-pagination
v-model="pagination"
:texts="{
nextPage: 'Seuraava sivu',
page: (page, pageCount) => `sivu ${page} / ${pageCount}`,
pageSize: 'Kohteita sivulla:',
pagination: 'Sivutus',
previousPage: 'Edellinen sivu',
range: (start, end, count) => `${start}–${end} / ${count}`,
}"
/>
To translate every pagination at once, set texts app-wide with applyDefaults({ 'c-pagination': { texts } }) (Customization → App-wide prop defaults); a per-instance texts still wins key by key. The app-wide texts also reach the pager inside c-data-table, except for keys the table's own texts set.
Accessibility
- The bar is a
<nav>landmark named bytexts.pagination. With several on a page, give each its own name. - The current page's button carries
aria-current="page". Page buttons are named bytexts.page, the arrows bytexts.previousPageandtexts.nextPage, and the arrows are disabled on the first and last page. The page-size button is named bytexts.pageSizefollowed by the current size ("Items per page: 25"). The ellipses are hidden from assistive technology and out of the tab order. - A page change is not announced. When the paged content updates elsewhere on the page, move focus to it, or announce the change, where the user needs to follow it.
Customization
Restyle through the parts: ::part(root) (the <nav>), ::part(details) (the page-size menu and the range text), ::part(items-per-page) (the menu's label and button) and ::part(pages) (the list of arrow and page buttons). The buttons are c-icon-buttons whose own parts are not forwarded. Colours come from the semantic tokens; override the tokens to re-theme.
Examples
<template>
<div>
<c-pagination v-model="options" />
<p>Current page: {{ options.page ?? 1 }}</p>
</div>
</template>
<script setup lang="ts">
import type { CPaginationOptions } from '@cscfi/csc-ui';
import { ref } from 'vue';
const options = ref<CPaginationOptions>({
itemCount: 96,
pageSize: 10,
pageSizes: [10, 25, 50],
});
</script>
<template>
<div>
<c-pagination v-model="options" hide-details simple />
<p>Current page: {{ options.page ?? 1 }}</p>
</div>
</template>
<script setup lang="ts">
import type { CPaginationOptions } from '@cscfi/csc-ui';
import { ref } from 'vue';
const options = ref<CPaginationOptions>({
itemCount: 40,
pageSize: 10,
});
</script>
API reference
<c-pagination>
A page navigation bar for a list split into pages: previous and next buttons around a window of page buttons, with a page-size menu and the range of items shown.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
hideDetails | hide-details | boolean | false | Hide the details row: the page-size menu and the "x - y of n items" text |
hideRange | hide-range | boolean | false | Hide the range text ("11 - 20 of 96 items"), keeping the page-size menu. |
simple | simple | boolean | false | Drop the page buttons and move previous and next to the bar's end; the range text is then the only sign of position. |
size | size | CPaginationSize | 'default' | Size of the controls: `small` renders the compact page buttons. |
texts | — | | {} app default | UI text overrides (i18n), merged over the English defaults. Objects have no attribute form — bind as a DOM property |
value | — | | () => ({ itemCount: 0 }) | The item count and the current page and page size; see `CPaginationOptions`. Bind it with `v-model`, or set it and listen to `change`. |
app default marks a prop you can set for every instance at once with applyDefaults() — an explicit attribute or property on an instance still wins.
Events
| Event | Detail | Description |
|---|---|---|
change | CPaginationOptions | Fired when the user picks a page or a page size, carrying a new value with the picked `page` and `pageSize` and the page's `startFrom` and `endTo`. |
input | void | Native bubbling input event dispatched alongside every value change so a plain `v-model` stays in sync. Carries no detail. |
update:value | CPaginationOptions | Fired alongside `change` with the same detail — the `v-model` contract. |
CSS parts
Style from outside with c-pagination::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The `<nav>` element wrapping the whole pagination bar |
details | The details area holding the items-per-page selector and range text |
items-per-page | The items-per-page row (label text and page-size menu) |
pages | The `<ul>` list of page buttons and the prev/next controls |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CPaginationOptions
The value of `c-pagination`. Set `itemCount`, and `page` and `pageSize` where the defaults do not fit; each change emits a new object with the picked `page` and `pageSize` and the `startFrom` / `endTo` range of the page's items.
export interface CPaginationOptions {
/** Index of the page's last item, from 0; set on the value it emits. */
endTo?: number;
/** Number of items to page through. */
itemCount: number;
/** The current page, from 1. Default 1. */
page?: number;
/** Items on a page. Default 25. */
pageSize?: number;
/** The page sizes the page-size menu offers. Default `[5, 25, 50, 100]`. */
pageSizes?: number[];
/** Index of the page's first item, from 0; set on the value it emits. */
startFrom?: number;
/** Most page buttons shown at once. Default 7. */
totalVisible?: number;
}CPaginationSize
Size of the pagination controls. `small` renders the compact page buttons.
export type CPaginationSize = 'default' | 'small';CPaginationTexts
UI texts of `c-pagination`, shallow-merged over the English defaults. Static labels are strings; interpolated ones are functions.
export interface CPaginationTexts {
/** Accessible name of the next-page button. */
nextPage?: string;
/** Accessible name of a page button; receives the page and the page count. */
page?: (page: number, pageCount: number) => string;
/** Label of the page-size menu. */
pageSize?: string;
/** Accessible name of the navigation landmark. */
pagination?: string;
/** Accessible name of the previous-page button. */
previousPage?: string;
/**
* The range of items shown; receives the first and the last item, from 1,
* and the item count.
*/
range?: (start: number, end: number, count: number) => string;
}