Lightweight Accessible Pagination Web Component – wc-pagination

wc-pagination is a Web Component that adds compact numbered pagination controls to paged lists, tables, search results, and other data views.

It automatically generates the page selector from the total record count, current page, and number of records per page.

Note that the web component manages the navigation UI and current-page state. Your app should handle the records themselves through local data slicing or an existing server request.

Features:

• First and last page controls beside the numbered buttons.
• Compact three-page number window for larger result sets.
• Ellipsis controls for moving across distant page ranges.
• Arrow, Home, and End keyboard navigation.
• ARIA labels, current-page state, live announcements, and visible focus styles.
• Host CSS custom properties for active and inactive colors.
• Page change events for connecting the control to application logic.

How To Use It:

Installation

Download wc-pagination.js and load it as an ES module. The script registers the <wc-pagination> custom element when the module executes.

<script type="module" src="/js/wc-pagination.js"></script>

Basic Usage

Place the custom element where the page controls should appear. Set total to the full record count, current to the initial page, and page-size to the number of records represented by each page.

<wc-pagination
  total="240"
  current="1"
  page-size="20">
</wc-pagination>

Attributes And Properties

The component watches three HTML attributes:

• total (number): Total number of records. The value is 0 when the attribute is omitted.
• current (number): Current page number. The fallback value is 1.
• page-size (number): Number of records represented by each page. The fallback value is 10.

JavaScript exposes the related state through total, current, pageSize, and totalPages. current has a setter. Update total and page-size through their attributes.

Programmatic changes rerender the control. Assigning a new current value also fires the page-change event.

const pagination = document.querySelector('wc-pagination');
pagination.current = 4;
pagination.setAttribute('total', '360');
pagination.setAttribute('page-size', '24');
console.log(pagination.totalPages);

Keep programmatically assigned page numbers between 1 and totalPages. Direct assignments are not clamped to the available page range.

Responding To Page Changes

Listen directly on the custom element when the selected page controls local data. The page-change event stores the new page number in event.detail.page and does not bubble to parent elements.

This example calculates the matching range in an existing products array and sends that slice to a rendering function.

const pagination = document.querySelector('wc-pagination');
pagination.addEventListener('page-change', function (event) {
  const page = event.detail.page;
  const start = (page - 1) * pagination.pageSize;
  const visibleProducts = products.slice(
    start,
    start + pagination.pageSize
  );
  renderProducts(visibleProducts);
});

Styling And Customization

Override the CSS custom properties on <wc-pagination> for the supported color states.

• --active-background-color: Background of the current page.
• --active-text-color: Text color of the current page.
• --inactive-border-color: Border color for inactive controls.
• --inactive-text-color: Text color for inactive controls.
• --inactive-background-color: Background of inactive controls.

The component also defines --active-border-color, but the active page rule removes its border. Changing that property has no visible effect in the current styles.

wc-pagination {
  --active-background-color: #2563eb;
  --active-text-color: #fff;
  --inactive-border-color: #cbd5e1;
  --inactive-text-color: #334155;
  --inactive-background-color: #fff;
}

Keyboard Controls And Accessibility

Keyboard interaction works from the active pagination control:

• ArrowLeft moves to the previous page.
• ArrowRight moves to the next page.
• Home moves to the first page.
• End moves to the last page.
• Tab and Shift+Tab retain normal browser tab behavior.

The component maintains a single pagination button in the tab sequence and moves focus to the new current page after keyboard or pointer navigation.

Its generated markup includes a pagination navigation label, descriptive button labels, aria-current="page" on the selected page, visually hidden text for ellipsis controls, a polite live region for page changes, and a :focus-visible outline.

Alternatives:

• Universal Data Pagination Component – Pagination System
• Custom Pagination Component In JavaScript – tui.pagination
• Simple Table Paginator In Pure JavaScript – Paginator.js