🚀 Pagination UI <pagination-component>

A lightweight, reusable, framework-independent pagination component built using Web Components (Custom Elements + Shadow DOM). Easily integrates into any HTML/JS app with no external dependencies.

Description

<pagination-component> is a lightweight, reusable Web Component that provides navigational pagination controls for paginated data views. It is framework-agnostic and can be used with any frontend stack including plain HTML/JS, React, Vue, Svelte, etc.

This component supports dynamic page ranges, ellipses for skipped blocks, and emits navigation events to allow integration with your data-fetching or UI update logic.

NPM Link

📦 Features

• 🔌 Native Web Component (no framework needed)
• 📐 Supports page ranges, previous/next, ellipsis
• 💡 Emits a page-change event with all pagination info
• 🎨 Styleable via CSS variables
• ♻️ Reusable across frameworks (React, Vue, Svelte, etc.)
• 🧠 Auto-handles large lists and intelligent rendering

Live Demo

🔗 CodePen: https://codepen.io/driftblaze/pen/gbaYvpG

Installation

Option 1: NPM Package

npm i pagination-webcomponent

then import as

import ('pagination-webcomponent')

Option 2: Unpkg

<script type="module" src="https://unpkg.com/pagination-webcomponent"></script>

Option 3: Module Import

import './PaginationComponent.js';

Option 4: HTML Script Tag

<script type="module" src="/path/to/PaginationComponent.js"></script>

Usage Example

<pagination-component
  offset="0"
  per-page="10"
  total="100"
></pagination-component>

<script>
  const pagination = document.querySelector('pagination-component');
  pagination.addEventListener('page-change', (e) => {
    console.log('New offset:', e.detail.offset);
    // Fetch data using e.detail.offset and e.detail.limit
  });
</script>

Attributes

| Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------------- | | offset | Number | ✅ | The current item offset (e.g., 0, 10, 20, ...). Clamped to valid bounds. | | per-page | Number | ✅ | Number of items per page | | total | Number | ✅ | Total number of items |

All attributes are reflected and can be dynamically updated.

Events

page-change

Dispatched whenever the user changes the page.

Payload

{
  "offset": Number,      // New offset (e.g., 30)
  "limit": Number,       // Items per page (e.g., 10)
  "total": Number,       // Total items (e.g., 100)
  "totalPages": Number   // Derived total pages (e.g., 10)
}

Styling

The component is styled via Shadow DOM and accepts the following CSS custom properties:

| CSS Variable | Description | |-------------------------------|------------------------------------| | --pagination-background | Button background | | --pagination-text | Button text color | | --pagination-border | Button border color | | --pagination-hover | Button hover and active background | | --pagination-active-border | Active page border highlight | | --pagination-active-color | Active button text color |

To override them:

pagination-component {
    --pagination-background: #181118;
    --pagination-text: #ecdfe8;
    --pagination-border: #9c8c9a;
    --pagination-hover: #91379f;
    --pagination-active-border: #ffcaff;
    --pagination-active-color: #ecdfe8;
}

Accessibility

• Uses native <button> elements
• Includes appropriate disabled states
• Fully keyboard navigable

License

MIT License © 2025

Maintainer

This component is maintained by Yash Raj Bharti.