Skip to content
Kimenpre-v1documentation home
Color scheme

ki-pagination

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.

Theme for this example
Color scheme for this example
<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

AttributePropertyTypeDefaultDescription
boundariesboundariesnumber1Number of pages to display at each end of the numbered list.
compact-labelcompactLabelstring'Page {page} of {pages}'Localized stepper label template. Include {page} and {pages}.
href-templatehrefTemplatestring | undefined–Relative or HTTP(S) URL template for native navigation. Place {page} in the path, query or fragment, for example "?page={page}".
labellabelstring'Pagination'Accessible name of the navigation landmark. Distinguish multiple result sets.
load-more-labelloadMoreLabelstring'Load more'Localized visible label for the button that appends results.
next-labelnextLabelstring'Next page'Localized accessible name of the control that requests the next page.
pagepagenumber1Current 1-based page. Update it when the requested results are ready.
page-labelpageLabelstring'Page {page}'Localized accessible name template for numbered controls. Include {page}.
pagespagesnumber | undefined–Total number of result pages. Omit it until a page count is available.
previous-labelpreviousLabelstring'Previous page'Localized accessible name of the control that requests the previous page.
shownshownnumber | undefined–Displayed result count in load-more mode. Update it after appending results.
siblingssiblingsnumber1Number of pages to display on each side of the current page.
status-labelstatusLabelstring'Showing {shown} of {total} results'Localized polite count template. Include {shown} and {total}.
totaltotalnumber | undefined–Total result count in load-more mode. Required with shown for the count.
variantvariant"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

EventDetail typeDescription
ki-load-moreCustomEvent<void>Requests another batch. Append results in place and update shown.
ki-page-changeCustomEvent<{ 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

PartDescription
compactCurrent page and page count in the stepper.
gapDecorative marker for omitted pages.
listOrdered list of pages in the numbered variant.
load-moreButton that requests another batch.
navigationNamed navigation landmark.
nextNext-page control.
pageNumbered button or link.
previousPrevious-page control.
statusPolite 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.

TokenDescription
--ki-density-target-minThe 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-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness 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-gapGap between the compact count and direction controls.
--ki-pagination-current-bgBackground of the current page control.
--ki-pagination-current-fgInk for the current page control.
--ki-pagination-gapGap between numbered page controls.
--ki-pagination-item-backdrop-filterComplete backdrop filter for the page control.
--ki-pagination-item-bgResting background of a numbered page control.
--ki-pagination-item-bg-imageOptional image above the page control background color.
--ki-pagination-item-fgResting ink for page labels and status text.
--ki-pagination-item-hover-bgBackground of a hovered page control.
--ki-pagination-item-hover-fgInk for a hovered page control.
--ki-pagination-item-radiusCorner radius of numbered page controls and direction links.
--ki-pagination-item-sizeMinimum size of a numbered page control at standard density.
--ki-pagination-more-gapGap between the load-more button and the count.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.

Workshop

Open ki-pagination in Storybook