ki-pagination
@kimen/elements/ki-pagination- Source
- Agent reference
Use pagination for long tables, search results, and lists. Use numbered pages for direct access, compact pagination for a previous/next stepper, and Load more to append results in place. Show short lists in full and use a stepper for the steps of a task.
<ki-pagination page="5" pages="12" label="Search results pages"></ki-pagination><ki-pagination page="5" pages="12" variant="compact" label="Table pages"></ki-pagination><ki-pagination variant="load-more" shown="20" total="240" label="More search results"></ki-pagination>Numbered pagination switches to compact when its available inline size
is below 480 CSS pixels. Previous and next stay visible at the ends.
Set siblings and boundaries to adjust the numbered window.
Result updates and focus
Listen for ki-page-change to retrieve the requested page. Once the new
results are rendered, set the component’s page and focus the results
heading. Give the heading tabindex="-1" so it can receive focus without
adding a Tab stop. When appending results in response to ki-load-more,
keep focus on the button and set shown to the new count. The existing
polite status announces the update.
Use href-template="?page={page}" for server navigation. Page numbers
and available direction controls become links. With multiple paging
regions, use distinct landmark labels. Translate the button labels and
the text templates together.
API reference
When to use: paged tables, search results or long lists. Use compact for a previous/next stepper and load-more to append results in place.
When not to use: short lists that fit in one view or the steps of a task.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
boundaries | boundaries | number | 1 | Number of pages to display at each end of the numbered list. |
compact-label | compactLabel | string | 'Page {page} of {pages}' | Localized stepper label template. Include {page} and {pages}. |
href-template | hrefTemplate | string | undefined | – | Relative or HTTP(S) URL template for native navigation. Place {page} in the path, query or fragment, for example "?page={page}". |
label | label | string | 'Pagination' | Accessible name of the navigation landmark. Distinguish multiple result sets. |
load-more-label | loadMoreLabel | string | 'Load more' | Localized visible label for the button that appends results. |
next-label | nextLabel | string | 'Next page' | Localized accessible name of the control that requests the next page. |
page | page | number | 1 | Current 1-based page. Update it when the requested results are ready. |
page-label | pageLabel | string | 'Page {page}' | Localized accessible name template for numbered controls. Include {page}. |
pages | pages | number | undefined | – | Total number of result pages. Omit it until a page count is available. |
previous-label | previousLabel | string | 'Previous page' | Localized accessible name of the control that requests the previous page. |
shown | shown | number | undefined | – | Displayed result count in load-more mode. Update it after appending results. |
siblings | siblings | number | 1 | Number of pages to display on each side of the current page. |
status-label | statusLabel | string | 'Showing {shown} of {total} results' | Localized polite count template. Include {shown} and {total}. |
total | total | number | undefined | – | Total result count in load-more mode. Required with shown for the count. |
variant | variant | "compact" | "load-more" | "pages" | 'pages' | Numbered pages, a previous/next stepper, or a button to append results. Numbered pages switch to the stepper below 480 CSS pixels of available width. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-load-more | CustomEvent<void> | Requests another batch. Append results in place and update shown. |
ki-page-change | CustomEvent<{
page: number;
}> | Requests a different page. Update results and move focus to their heading when they are ready. Cancelling the event also cancels a plain link click. |
CSS parts
| Part | Description |
|---|---|
compact | Current page and page count in the stepper. |
gap | Decorative marker for omitted pages. |
list | Ordered list of pages in the numbered variant. |
load-more | Button that requests another batch. |
navigation | Named navigation landmark. |
next | Next-page control. |
page | Numbered button or link. |
previous | Previous-page control. |
status | Polite result-count announcement. |
CSS custom properties
The public styling contract of ki-pagination: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-focus-ring-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. |
--ki-pagination-compact-gap | Gap between the compact count and direction controls. |
--ki-pagination-current-bg | Background of the current page control. |
--ki-pagination-current-fg | Ink for the current page control. |
--ki-pagination-gap | Gap between numbered page controls. |
--ki-pagination-item-backdrop-filter | Complete backdrop filter for the page control. |
--ki-pagination-item-bg | Resting background of a numbered page control. |
--ki-pagination-item-bg-image | Optional image above the page control background color. |
--ki-pagination-item-fg | Resting ink for page labels and status text. |
--ki-pagination-item-hover-bg | Background of a hovered page control. |
--ki-pagination-item-hover-fg | Ink for a hovered page control. |
--ki-pagination-item-radius | Corner radius of numbered page controls and direction links. |
--ki-pagination-item-size | Minimum size of a numbered page control at standard density. |
--ki-pagination-more-gap | Gap between the load-more button and the count. |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-weight-body-medium | semantic font weight for typography weight body medium. |