Pagination
Page navigation control with previous/next arrows, numbered page buttons, and smart ellipsis truncation.
<arc-pagination>Overview
Pagination provides a compact navigation strip for moving between pages of content. It renders previous/next arrow buttons flanking a row of numbered page buttons, with ellipsis markers automatically inserted when the total page count exceeds what can be displayed. The first and last pages are always visible, and the siblings prop controls how many pages appear adjacent to the currently active page.
The component is declarative. Set total for the number of pages, current for the active page, and siblings for the visible range. When the user clicks a page or arrow, an arc-change event fires with the new page number, letting you update your data source and re-render. Previous and next buttons are automatically disabled at the boundaries.
Pagination follows the WAI-ARIA pattern for navigation landmarks with role="navigation" and aria-label="Pagination". Each page button carries aria-current="page" when active, and the arrow buttons include descriptive aria-labels. The active page gets an accent-primary highlight with a soft glow.
Guidelines
When to use
- Always set `total` to reflect the actual number of pages in your dataset
- Use `siblings="1"` for compact layouts or `siblings="2"` when space allows for easier scanning
- Listen to `arc-change` and update your data source to load the corresponding page
- Place Pagination below or adjacent to the content it controls for clear spatial association
- Combine with a page-size selector when users should control how many items appear per page
When not to use
- Do not use Pagination for fewer than 3 pages: inline previous/next links are simpler
- Do not set `current` to a value outside the 1..total range: the component clamps internally but the intent is unclear
- Do not nest Pagination inside other interactive controls like buttons or links
- Do not use Pagination to navigate between unrelated sections; use Tabs instead
- Avoid hiding the component when there is only one page: instead disable or show a single page indicator so users understand the data scope
Features
- Smart ellipsis truncation that always shows the first page, last page, and siblings around the current page
- Configurable `siblings` prop to control how many page numbers appear next to the active page
- Previous and next arrow buttons that auto-disable at page boundaries
- Active page highlighted with accent-primary background and a subtle box-shadow glow
- Accessible navigation landmark with `role="navigation"` and `aria-current="page"` on the active button
- Hover and focus-visible states with border brightening and focus glow ring
- Fires `arc-change` with the new page number on every navigation action
Preview
Usage
This component requires JavaScript. No pure HTML/CSS version is available. Use the Web Component directly or a framework wrapper.
<arc-pagination total="10" current="3" siblings="1"></arc-pagination>import { Pagination } from '@arclux/arc-ui-react';
export default function Example() {
return (
<Pagination total="10" current="3" siblings="1" />
);
}<script setup>
import { Pagination } from '@arclux/arc-ui-vue';
</script>
<template>
<Pagination total="10" current="3" siblings="1" />
</template><script>
import { Pagination } from '@arclux/arc-ui-svelte';
</script>
<Pagination total="10" current="3" siblings="1" />import { Component } from '@angular/core';
import { Pagination } from '@arclux/arc-ui-angular';
@Component({
imports: [Pagination],
template: `
<arc-pagination total="10" current="3" siblings="1"></arc-pagination>
`,
})
export class MyComponent {}import { Pagination } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<Pagination total="10" current="3" siblings="1" />
);
}import { Pagination } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<Pagination total="10" current="3" siblings="1" />
);
}API
totalnumber1- Total number of pages. At least 1: a pager with no pages is still a pager showing page 1 of 1.
currentnumber1- The currently active page number (1-based). Reflected as an attribute. Clamped to 1..
total, so a page number past either end lands on the nearest real page rather than stranding the control. siblingsnumber1- Number of page buttons to show on each side of the current page before ellipsis truncation kicks in. Never negative.
compactbooleanfalse- Shows only previous/next buttons with a 'current / total' label. Hides individual page numbers.
Events
arc-changedetail:{ value: number }- Fired when the current page changes
See Also
- Data GridA spreadsheet-grade grid for working with tabular data: inline cell editing, multi-column sorting, pinned columns, row selection, and virtualized rendering. Columns are defined as a JavaScript array, and the grid implements the full WAI-ARIA grid keyboard pattern with a single tab stop.
- BreadcrumbNavigation trail that shows the user's current location in a page hierarchy, with separator icons and current-page indication.
- Infinite ScrollIntersection Observer-powered container that fires a load event when the user scrolls near the bottom, with built-in loading spinner and end-of-list state.