Pagination

Table of Contents

Examples

Basic Usage
With Controls
Left and Right Slots
Simple Preconfigured
Full Preconfigured
All Controls Manually
Goto Page
Items Per Page Options
Live Demo

JavaScript Reference

Constructor
Requirements
Properties
Methods
Events
Built-in Controls

A pagination interface component that tracks the current page, calculates total pages from total-items and items-per-page, and emits a page-change event when the pagination state changes. It does not manage or render the paginated content — it is a pure navigation interface. Place it beneath your content and listen for page-change to know when to load new content.

Toolbar controls are slotted in — mix and match the built-in controls listed below, or write your own by extending Control from controls/Control.js. Use the controls attribute for preconfigured sets.

Basic Usage

Without any controls the component tracks state but renders nothing visible — useful when you supply your own UI.

<k-pagination id="pagination1" total-items="100">
  <button id="back">Back</button>
  <button id="next">Next</button>
  <span id="pageNumber">1</span>
</k-pagination>
<script>
  const p1 = document.getElementById('pagination1');
  p1.addEventListener('page-change', ()=> {
    document.getElementById('pageNumber').innerText = p1.page;
  });
  document.getElementById("back").addEventListener('click', () => {
    p1.previousPage();
  });
  document.getElementById("next").addEventListener('click', () => {
    p1.nextPage();
  });
</script>

With Controls

Slot any combination of built-in controls directly inside <k-pagination>. Import only what you need. By default, controls go in the left side. Use slot="right" to push controls to the right side with automatic spacing.

<k-pagination total-items="100">
  <kc-pg-prev></kc-pg-prev>
  <kc-pg-page-info></kc-pg-page-info>
  <kc-pg-next></kc-pg-next>
  <kc-pg-items-per-page slot="right"></kc-pg-items-per-page>
</k-pagination>

Simple Preconfigured

Use controls="simple" for a minimal previous / page-info / next toolbar. All required control modules are loaded automatically.

<k-pagination total-items="100" controls="simple"></k-pagination>

Full Preconfigured

Use controls="full" for a complete toolbar: first / previous / page-info / next / last + items-per-page selector.

<k-pagination total-items="100" controls="full"></k-pagination>

All Controls Manually

Slot all available controls yourself for full control over order and composition. Controls without slot="right" go on the left; controls with slot="right" are pushed to the right side with automatic spacing.

<k-pagination total-items="100">
  <kc-pg-first></kc-pg-first>
  <kc-pg-prev></kc-pg-prev>
  <kc-pg-page-info></kc-pg-page-info>
  <kc-pg-goto-page></kc-pg-goto-page>
  <kc-pg-count></kc-pg-count>
  <kc-pg-next></kc-pg-next>
  <kc-pg-last></kc-pg-last>
  <kc-pg-items-per-page slot="right"></kc-pg-items-per-page>
</k-pagination>

Goto Page

Use <kc-pg-goto-page> and <kc-pg-count> together for an interactive “Page X of Y” control where X is a dropdown the user can select directly.

<k-pagination total-items='100'> Page <kc-pg-goto-page></kc-pg-goto-page> of <kc-pg-count></kc-pg-count>
</k-pagination>

Page of

Items Per Page Options

Use the options attribute on <kc-pg-items-per-page> to customize the available page-size choices. Pass a comma-separated list of numbers. Defaults to 5,10,25,50,100. Typically placed on the right with slot="right".

<k-pagination total-items='100'>
  <kc-pg-prev></kc-pg-prev>
  <kc-pg-page-info></kc-pg-page-info>
  <kc-pg-next></kc-pg-next>
  <kc-pg-items-per-page slot='right' options='5,10,20,50'></kc-pg-items-per-page>
</k-pagination>

Live Demo

Listen for page-change to re-render content whenever the pagination state updates (either from user navigation or configuration changes). The event detail carries the full pagination state so your content layer knows exactly which slice to show.

<div id="pgDemoCards"></div>
<k-pagination id="pgLive" total-items="47" controls="full"></k-pagination>
<script>
  (function(){
    const pg = document.getElementById('pgLive');
    const container = document.getElementById('pgDemoCards');
    const renderCards = ({ currentPage, itemsPerPage, totalItems }) => {
      const start = (currentPage - 1) * itemsPerPage + 1;
      const end = Math.min(currentPage * itemsPerPage, totalItems);
      container.innerHTML = '';
      for(let i = start; i <= end; i++){
        const card = document.createElement('k-card');
        card.textContent = 'Item ' + i;
        container.appendChild(card);
      }
    };
    pg.addEventListener('page-change', e => renderCards(e.detail));
    renderCards({ currentPage: 1, itemsPerPage: 10, totalItems: 47 });
  })();
</script>

JavaScript Reference

Constructor

new Pagination();

Requirements

Import the main component. When using controls, import each control individually or use the controls attribute which auto-imports all control modules.

Properties

Property / Attribute	Type	Default	Description
`totalItems` / `total-items`	Number	`0`	Total number of items across all pages. Used to calculate `totalPages`.
`itemsPerPage` / `items-per-page`	Number	`10`	Number of items shown per page. Changing this resets the current page to 1 and fires `items-per-page-change`.
`controls`	String	`''`	Preconfigured control set. One of `'simple'` or `'full'`. Auto-imports the required control modules.
`page`	Number	`1`	The current page number. Reflects to the `page` attribute. Set directly (`el.page = 3`) or via attribute; value is automatically clamped to `[1, totalPages]`.
`totalPages` (readonly)	Number	`1`	Total number of pages, calculated as `Math.ceil(totalItems / itemsPerPage)`. Read-only.

Methods

Method	Description
`nextPage()`	Advance to the next page. No-op when already on the last page.
`previousPage()`	Go back to the previous page. No-op when already on the first page.

Events

Event	Detail	Description
`page-change`	`{ currentPage, totalPages, itemsPerPage, totalItems }`	Fired when the current page changes due to user navigation (`.page`, `nextPage()`, `previousPage()`) or when configuration changes cause page adjustment.

Built-in Controls

Each control is a separate custom element that finds its parent <k-pagination> and wires up automatically. Import only the controls you need.

Tag	Import	Description
`<kc-pg-first>`	`controls/PgFirst.js`	Jumps to page 1. Disabled when already on page 1.
`<kc-pg-prev>`	`controls/PgPrev.js`	Goes to the previous page. Disabled when on page 1.
`<kc-pg-page-info>`	`controls/PgPageInfo.js`	Displays “Page X of Y” text.
`<kc-pg-next>`	`controls/PgNext.js`	Goes to the next page. Disabled when on the last page.
`<kc-pg-last>`	`controls/PgLast.js`	Jumps to the last page. Disabled when already on the last page.
`<kc-pg-items-per-page>`	`controls/PgItemsPerPage.js`	A select input for choosing items per page. Defaults to options 10, 25, 50, 100. Use the `options` attribute with a comma-separated list to customize (e.g. `options="5,10,20"`). Resets to page 1 on change. The label text is slotted — override it with children (e.g. `<kc-pg-items-per-page>Per page:</kc-pg-items-per-page>`).
`<kc-pg-goto-page>`	`controls/PgGotoPage.js`	A dropdown listing every page number. Selecting a value navigates directly to that page.
`<kc-pg-count>`	`controls/PgCount.js`	Displays the total page count as plain text. Pair with `<kc-pg-goto-page>` to build a “Page X of Y” control.

Kempo UI

Components

Base Components

Utils

Pagination

Examples