Data and Identity

Stable - @kikita-labs/ui v2.0.0

Pagination

Page navigation with numbers, steps, a summary and a rows-per-page picker.

Import

Pagination is a standalone component built from the kit's Button, IconButton and Select, plus a static ellipsis.

pagination.ts
import { KuiPagination } from '@kikita-labs/ui';

Usage

Open in Playground

Bind currentPage with a signal. The current page carries aria-current and its own name, so the state is never colour alone.

Current page: 3
<div class="pagination-example">
  <kui-pagination ariaLabel="Project pages" [totalPages]="10" [(currentPage)]="page" />
  <span>Current page: {{ page() }}</span>
</div>

currentPage and pageSize are plain two-way bindings, not form values: pagination is page-level navigation state and is never placed inside kui-field.

Variants and sizes

compact (default) shows First, Prev, numbers and Next, Last. simple shows Prev, Page X of Y and Next for narrow layouts. full adds the Showing X to Y of Z summary and the rows-per-page picker. disabled blocks every control.

Showing 26–50 of 289
<div class="pagination-example">
  <kui-pagination
    ariaLabel="Simple pages"
    variant="simple"
    [totalPages]="12"
    [(currentPage)]="page"
  />
  <kui-pagination
    ariaLabel="Full pages"
    variant="full"
    [totalPages]="12"
    [totalItems]="289"
    [(currentPage)]="page"
    [(pageSize)]="pageSize"
  />
  <kui-pagination
    ariaLabel="Disabled pages"
    size="sm"
    [totalPages]="12"
    [(currentPage)]="page"
    disabled
  />
</div>

Page window

siblingCount is how many numbers show beside the current page before an ellipsis, and boundaryCount how many always show at each edge. The ellipsis is a static aria-hidden span, never a button.

<div class="pagination-example">
  <kui-pagination
    ariaLabel="Wide window pages"
    [totalPages]="42"
    [siblingCount]="2"
    [boundaryCount]="1"
    [(currentPage)]="page"
  />
  <kui-pagination
    ariaLabel="Edge window pages"
    [totalPages]="42"
    [siblingCount]="0"
    [boundaryCount]="2"
    [(currentPage)]="page"
  />
</div>

Usage with a table

Pagination is a sibling of table[kuiTable], not nested in it: a table only allows table parts as children and holds the full dataset without a slicing concept. Page state is owned by the consuming component, as with mat-paginator and mat-table.

IdName
1Project 1
2Project 2
3Project 3
4Project 4
5Project 5
6Project 6
7Project 7
8Project 8
9Project 9
10Project 10
Showing 1–10 of 60
<div class="pagination-example">
  <table kuiTable [data]="pageRows()">
    <thead>
      <tr>
        <th kuiTh>Id</th>
        <th kuiTh>Name</th>
      </tr>
    </thead>
    <tbody>
      @for (row of pageRows(); track row.id) {
        <tr kuiRow [value]="row">
          <td kuiCell>{{ row.id }}</td>
          <td kuiCell>{{ row.name }}</td>
        </tr>
      }
    </tbody>
  </table>

  <kui-pagination
    ariaLabel="Table pages"
    variant="full"
    [totalPages]="totalPages()"
    [totalItems]="allRows.length"
    [pageSizeOptions]="[10, 20, 30]"
    [(currentPage)]="page"
    [(pageSize)]="pageSize"
  />
</div>

Changing the rows-per-page picker sets pageSize and resets currentPage to 1 in the same update, since a stale page offset into a resized list would be wrong.

Provider defaults

Set defaults.pagination once for the application or for a subtree. Each option resolves as local input > defaults.pagination.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        pagination: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
variant'full' | 'compact' | 'simple' — Layout variant.
siblingCountnumber — Pages shown on each side of the current page.
boundaryCountnumber — Pages always shown at each edge.
pageSizeOptionsreadonly number[] — Choices offered by the rows-per-page picker of the full variant.
firstIconKuiIconGlyph — Icon of the first-page button. Takes precedence over defaults.icons.first. See Structural Icons.
previousIconKuiIconGlyph — Icon of the previous control. Takes precedence over defaults.icons.previous. See Structural Icons.
nextIconKuiIconGlyph — Icon of the next control. Takes precedence over defaults.icons.next. See Structural Icons.
lastIconKuiIconGlyph — Icon of the last-page button. Takes precedence over defaults.icons.last. See Structural Icons.

Theming tokens

Set any of these on the component or an ancestor to restyle one part. Each token is optional: when it is not set, the part uses the role or scale token in the default column.

NameTypeDefaultDescription
--kui-pagination-simple-label-colorCSS custom property--kui-color-textSimple label color
NameTypeDefaultDescription
--kui-pagination-summary-font-sizeCSS custom property--kui-text-xs-sizeSummary font size
--kui-pagination-ellipsis-font-sizeCSS custom property--kui-text-sm-sizeEllipsis font size
--kui-pagination-simple-label-font-sizeCSS custom property--kui-text-sm-sizeSimple label font size
--kui-pagination-simple-label-padding-inlineCSS custom property--kui-space-2Simple label padding, inline
--kui-pagination-page-size-gapCSS custom property--kui-space-2Page size gap
--kui-pagination-page-size-label-font-sizeCSS custom property--kui-text-xs-sizePage size label font size

Messages

Every text the component owns (accessible names, visible words, announcements) is a typed message with an English default. Override it for the application with provideKikitaUi({ messages }), or for a subtree with provideKuiMessages.

NameTypeDefaultDescription
labelstring — Accessible name of the navigation landmark. Default Pagination.
firststring — First page button. Default First page.
previousstring — Previous page button. Default Previous page.
nextstring — Next page button. Default Next page.
laststring — Last page button. Default Last page.
pageKuiMessageFn<{ page: number; current: boolean; }> — Accessible name of one page button. Default Page {page} or Page {page}, current.
rowsPerPagestring — Label of the rows per page picker. Default Rows per page.
summaryKuiMessageFn<{ start: number; end: number; total: number; }> — Summary text. Default Showing {start}–{end} of {total}.
simplePageKuiMessageFn<{ page: number; total: number; }> — Label of the simple variant. Default Page {page} of {total}.

API

Inputs verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
variant'full' | 'compact' | 'simple' | undefinedundefinedLayout preset (defaults.pagination.variant, then compact). compact is First, Prev, numbers with ellipsis, Next and Last; simple is Prev, "Page X of Y" and Next; full adds the summary and the rows-per-page picker.
size'xs' | 'sm' | 'md' | 'lg' | undefinedundefinedControl size on the Button scale. Falls back to the root defaults.size, then md.
totalPagesnumber-Required total page count. Static numeric values are coerced; an invalid or non-positive value uses 1.
[(currentPage)]number1Current page, 1-based. A plain two-way model, not a form value, so pagination is never placed in kui-field. An out-of-range binding is clamped.
siblingCountnumber | undefinedundefinedPage numbers shown beside the current page before an ellipsis (defaults.pagination.siblingCount, then 1).
boundaryCountnumber | undefinedundefinedPage numbers always shown at each edge (defaults.pagination.boundaryCount, then 1).
[(pageSize)]number25Rows per page, used by the full variant. Changing the picker sets pageSize and resets currentPage to 1 in the same update.
pageSizeOptionsreadonly number[] | undefinedundefinedChoices of the rows-per-page picker, full variant only (defaults.pagination.pageSizeOptions, then [10, 25, 50, 100]).
totalItemsnumber | undefinedtotalPages * pageSizeTotal item count for the "Showing X-Y of Z" summary, full variant only.
disabledbooleanfalseDisables every control with the native attribute, removing them from the tab order.
ariaLabelstring | undefinedundefinedAccessible name of the nav landmark. Falls back to the pagination.label message (Pagination).
messagesPartial<KuiPaginationMessages> | undefinedundefinedPer-instance text overrides: button names, rowsPerPage, summary and page. They win over scoped and root messages.
(currentPageChange)number-Emitted whenever currentPage changes (model output).
(pageSizeChange)number-Emitted whenever pageSize changes (model output).
--kui-pagination-gap / -summary-gap / -ellipsis-colorCSS custom properties-Gap between the controls, gap between the summary row and the controls, and the ellipsis and secondary text colour.
--kui-pagination-page-min-size-{xs,sm,md,lg} / -page-size-widthCSS custom properties-Square size of the page-number buttons per size and the fixed width (76px) of the rows-per-page picker.
KuiPaginationOptionsinterface-Shape of defaults.pagination: variant, siblingCount, boundaryCount, pageSizeOptions and the four step icons.

Accessibility

Pagination is a set of independent buttons in a navigation landmark.

  • The controls sit in a nav landmark named by ariaLabel or the pagination.label message, separate from the primary navigation.
  • The current page has aria-current="page" and the name Page N, current.
  • First, Prev, Next and Last are icon buttons with a required aria-label; at the range boundary they get the native disabled attribute and leave the tab order.
  • The ellipsis is aria-hidden and not focusable.
  • The full-variant summary is aria-live="polite".
  • There is no roving tabindex or arrow-key navigation: Tab and Shift+Tab move between the non-disabled controls in visual order, and Enter or Space activates the focused one.

Known gaps

Documented limits of the installed package.

  • There is no jump-to-page input; add a Number Input next to the group if a product needs it.
  • The ellipsis is static and has no hover-to-jump affordance.
  • The rows-per-page select sits in a label-less field with an aria-label on the input, so the open listbox panel carries no separate name.
  • A formal assistive-technology review has not been run.