Pagination
Page navigation control with previous/next arrows, numbered page buttons, and smart ellipsis truncation.
<arc-pagination> Overview
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.
-
currentnumber1 - The currently active page number (1-based). Reflected as an attribute.
-
siblingsnumber1 - Number of page buttons to show on each side of the current page before ellipsis truncation kicks in.
-
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 Table A data-driven table component that renders rows from a JavaScript array. Declarative column definitions via `arc-column` children control which fields appear, their headers, widths, and sort behavior. Built-in support for column sorting, row selection with checkboxes, and an empty-state fallback.
- Breadcrumb Wayfinding navigation trail that shows the user their current location within a hierarchical page structure, with separator icons and current-page indication.
- Infinite Scroll Intersection 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.