import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
paginationClass, paginationContentClass, paginationLinkClass,
} from '#components/ui/pagination.ts';
import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from '#lib/ui/lucide.ts';
export default function PaginationDemo() {
return html`
<nav role="navigation" aria-label="pagination" data-slot="pagination" class=${paginationClass()}>
<ul data-slot="pagination-content" class=${paginationContentClass()}>
<li data-slot="pagination-item">
<a href="#" aria-label="Go to previous page" data-slot="pagination-link" data-active="false" class=${cn(paginationLinkClass({ size: 'default' }), 'pl-1.5!')}>
${ChevronLeftIcon('cn-rtl-flip')}
<span class="hidden sm:block">Previous</span>
</a>
</li>
<li data-slot="pagination-item">
<a href="#" data-slot="pagination-link" data-active="false" class=${paginationLinkClass()}>1</a>
</li>
<li data-slot="pagination-item">
<a href="#" aria-current="page" data-slot="pagination-link" data-active="true" class=${paginationLinkClass({ isActive: true })}>
2
</a>
</li>
<li data-slot="pagination-item">
<a href="#" data-slot="pagination-link" data-active="false" class=${paginationLinkClass()}>3</a>
</li>
<li data-slot="pagination-item">
<span aria-hidden="true" data-slot="pagination-ellipsis" class="flex size-8 items-center justify-center [&_svg:not([class*='size-'])]:size-4">
${MoreHorizontalIcon()}
<span class="sr-only">More pages</span>
</span>
</li>
<li data-slot="pagination-item">
<a href="#" aria-label="Go to next page" data-slot="pagination-link" data-active="false" class=${cn(paginationLinkClass({ size: 'default' }), 'pr-1.5!')}>
<span class="hidden sm:block">Next</span>
${ChevronRightIcon('cn-rtl-flip')}
</a>
</li>
</ul>
</nav>
`;
}
View Code
Installation
Copy and paste the following code into your project.
/**
* Pagination: page navigation. Tier-1 class helpers; compose with native
* `<nav>` + `<ul>` + `<li>` + `<a>`. Links route through `buttonClass()`
* so the visual matches the rest of the button vocabulary exactly.
*
* shadcn parity:
* Pagination → <nav aria-label="pagination" class=${paginationClass()}>
* PaginationContent → paginationContentClass()
* PaginationItem → <li> (no helper needed)
* PaginationLink → paginationLinkClass({ isActive, size })
* PaginationPrevious → paginationPreviousClass()
* PaginationNext → paginationNextClass()
* PaginationEllipsis → paginationEllipsisClass()
*
* A11y (required for accessible output): wrap the list in <nav
* aria-label="pagination">, set aria-current="page" on the active page
* link, give an icon-only Previous / Next control an aria-label, and mark
* the ellipsis aria-hidden="true". The class helpers emit none of these.
*
* Design tokens used: inherited from buttonClass.
*
* @example
* ```html
* <nav role="navigation" aria-label="pagination" class=${paginationClass()}>
* <ul class=${paginationContentClass()}>
* <li><a class=${paginationPreviousClass()} href="?page=1">‹ Previous</a></li>
* <li><a class=${paginationLinkClass({ isActive: false })} href="?page=2">2</a></li>
* <li><a class=${paginationLinkClass({ isActive: true })} aria-current="page">3</a></li>
* <li class=${paginationEllipsisClass()} aria-hidden="true">
* <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><circle cx="12" cy="12" r="1" /><circle cx="19" cy="12" r="1" /><circle cx="5" cy="12" r="1" /></svg>
* </li>
* <li><a class=${paginationNextClass()} href="?page=4">Next ›</a></li>
* </ul>
* </nav>
* ```
*/
import { cn } from '../lib/utils.ts';
import { buttonClass, type ButtonSize } from './button.ts';
export const paginationClass = (): string => 'mx-auto flex w-full justify-center';
export const paginationContentClass = (): string => 'flex-row gap-1 flex items-center';
export function paginationLinkClass(opts: { isActive?: boolean; size?: ButtonSize } = {}): string {
return cn(buttonClass({ variant: opts.isActive ? 'outline' : 'ghost', size: opts.size ?? 'icon' }));
}
export const paginationPreviousClass = (): string =>
cn(buttonClass({ variant: 'ghost', size: 'default' }), 'gap-1 px-2.5 sm:ps-2.5');
export const paginationNextClass = (): string =>
cn(buttonClass({ variant: 'ghost', size: 'default' }), 'gap-1 px-2.5 sm:pe-2.5');
export const paginationEllipsisClass = (): string => 'size-9 flex items-center justify-center';
Update the import paths to match your project setup.
Usage
import {
paginationClass,
paginationContentClass,
paginationLinkClass,
paginationPreviousClass,
paginationNextClass,
paginationEllipsisClass,
} from '#components/ui/pagination.ts';
<nav aria-label="pagination" class=${paginationClass()}>
<ul class=${paginationContentClass()}>
<li>
<a href="#" aria-label="Go to previous page" class=${paginationPreviousClass()}>Previous</a>
</li>
<li>
<a href="#" class=${paginationLinkClass()}>1</a>
</li>
<li>
<a href="#" aria-current="page" class=${paginationLinkClass({ isActive: true })}>2</a>
</li>
<li>
<a href="#" class=${paginationLinkClass()}>3</a>
</li>
<li class=${paginationEllipsisClass()} aria-hidden="true">...</li>
<li>
<a href="#" aria-label="Go to next page" class=${paginationNextClass()}>Next</a>
</li>
</ul>
</nav>
Composition
Use the following composition to build a pagination:
paginationClass(), on a nav
└── paginationContentClass(), on a ul
├── li
│ └── paginationPreviousClass(), on an a
├── li
│ └── paginationLinkClass(), on an a
├── paginationEllipsisClass(), on an li
└── li
└── paginationNextClass(), on an a
Simple
A simple pagination with only page numbers.
import { html } from '@webjsdev/core';
import {
paginationClass, paginationContentClass, paginationLinkClass,
} from '#components/ui/pagination.ts';
export default function PaginationSimple() {
return html`
<nav role="navigation" aria-label="pagination" data-slot="pagination" class=${paginationClass()}>
<ul data-slot="pagination-content" class=${paginationContentClass()}>
<li data-slot="pagination-item">
<a href="#" data-slot="pagination-link" data-active="false" class=${paginationLinkClass()}>1</a>
</li>
<li data-slot="pagination-item">
<a href="#" aria-current="page" data-slot="pagination-link" data-active="true" class=${paginationLinkClass({ isActive: true })}>
2
</a>
</li>
<li data-slot="pagination-item">
<a href="#" data-slot="pagination-link" data-active="false" class=${paginationLinkClass()}>3</a>
</li>
<li data-slot="pagination-item">
<a href="#" data-slot="pagination-link" data-active="false" class=${paginationLinkClass()}>4</a>
</li>
<li data-slot="pagination-item">
<a href="#" data-slot="pagination-link" data-active="false" class=${paginationLinkClass()}>5</a>
</li>
</ul>
</nav>
`;
}
View Code
Icons Only
Use just the previous and next buttons without page numbers. This is useful for data tables with a rows per page selector.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import {
paginationClass, paginationContentClass, paginationLinkClass,
} from '#components/ui/pagination.ts';
import { selectTriggerClass } from '#components/ui/select.ts';
import { ChevronLeftIcon, ChevronRightIcon } from '#lib/ui/lucide.ts';
export default function PaginationIconsOnly() {
return html`
<div class="flex items-center justify-between gap-4">
<div role="group" data-slot="field" data-orientation="horizontal" class=${cn(fieldClass({ orientation: 'horizontal' }), 'w-fit')}>
<label data-slot="field-label" for="select-rows-per-page" class=${fieldLabelClass()}>Rows per page</label>
<ui-select>
<select id="select-rows-per-page" class=${cn(selectTriggerClass(), 'w-20')}>
<option value="10">10</option>
<option value="25" selected>25</option>
<option value="50">50</option>
<option value="100">100</option>
</select>
</ui-select>
</div>
<nav role="navigation" aria-label="pagination" data-slot="pagination" class=${cn(paginationClass(), 'mx-0 w-auto')}>
<ul data-slot="pagination-content" class=${paginationContentClass()}>
<li data-slot="pagination-item">
<a href="#" aria-label="Go to previous page" data-slot="pagination-link" data-active="false" class=${cn(paginationLinkClass({ size: 'default' }), 'pl-1.5!')}>
${ChevronLeftIcon()}
<span class="hidden sm:block">Previous</span>
</a>
</li>
<li data-slot="pagination-item">
<a href="#" aria-label="Go to next page" data-slot="pagination-link" data-active="false" class=${cn(paginationLinkClass({ size: 'default' }), 'pr-1.5!')}>
<span class="hidden sm:block">Next</span>
${ChevronRightIcon()}
</a>
</li>
</ul>
</nav>
</div>
`;
}
View Code
Client-Side Navigation
A page link is a plain <a href>, and the WebJs client router picks it up on its own, with prefetch and a soft navigation. Use a real page URL such as ?page=3 in the href so the links also work with JavaScript off.
<a href="?page=3" class=${paginationLinkClass()}>3</a>
Note: Because the links are native anchors, no change to pagination.ts is needed for routing.
RTL
To enable RTL support, see the RTL configuration guide.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
paginationClass, paginationContentClass, paginationLinkClass,
} from '#components/ui/pagination.ts';
import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from '#lib/ui/lucide.ts';
// shadcn's demo switches language with a selector; the page shows its
// default, Arabic, with Arabic numerals. Its RTL build turns the padding
// logical and flips the chevrons, which the classes here do by hand.
const translations = {
en: { dir: 'ltr', values: { previous: 'Previous', next: 'Next' } },
ar: { dir: 'rtl', values: { previous: 'السابق', next: 'التالي' } },
he: { dir: 'rtl', values: { previous: 'הקודם', next: 'הבא' } },
};
const ARABIC_NUMERALS = ['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩'];
const toArabicNumerals = (num: number) =>
num.toString().split('').map((digit) => ARABIC_NUMERALS[Number(digit)]).join('');
export default function PaginationRtl() {
const { dir, values: t } = translations.ar;
return html`
<nav role="navigation" aria-label="pagination" dir=${dir} data-slot="pagination" class=${paginationClass()}>
<ul data-slot="pagination-content" class=${paginationContentClass()}>
<li data-slot="pagination-item">
<a href="#" aria-label="Go to previous page" data-slot="pagination-link" data-active="false" class=${cn(paginationLinkClass({ size: 'default' }), 'ps-1.5!')}>
${ChevronLeftIcon('rtl:rotate-180')}
<span class="hidden sm:block">${t.previous}</span>
</a>
</li>
<li data-slot="pagination-item">
<a href="#" data-slot="pagination-link" data-active="false" class=${paginationLinkClass()}>${toArabicNumerals(1)}</a>
</li>
<li data-slot="pagination-item">
<a href="#" aria-current="page" data-slot="pagination-link" data-active="true" class=${paginationLinkClass({ isActive: true })}>
${toArabicNumerals(2)}
</a>
</li>
<li data-slot="pagination-item">
<a href="#" data-slot="pagination-link" data-active="false" class=${paginationLinkClass()}>${toArabicNumerals(3)}</a>
</li>
<li data-slot="pagination-item">
<span aria-hidden="true" data-slot="pagination-ellipsis" class="flex size-8 items-center justify-center [&_svg:not([class*='size-'])]:size-4">
${MoreHorizontalIcon()}
<span class="sr-only">More pages</span>
</span>
</li>
<li data-slot="pagination-item">
<a href="#" aria-label="Go to next page" data-slot="pagination-link" data-active="false" class=${cn(paginationLinkClass({ size: 'default' }), 'pe-1.5!')}>
<span class="hidden sm:block">${t.next}</span>
${ChevronRightIcon('rtl:rotate-180')}
</a>
</li>
</ul>
</nav>
`;
}
View Code
Changelog
RTL Support
The previous and next labels can be translated as they are: the kit's helpers style an anchor you write yourself, so the label is already your own text. Give the chevrons the rtl:rotate-180 class so they point the right way in a right-to-left page, and use the logical ps-1.5! and pe-1.5! paddings, as the RTL example above does.
API Reference
Every part is a class helper for a native element. The helpers emit no ARIA, so add it yourself: wrap the list in <nav aria-label="pagination">, set aria-current="page" on the active link, give an icon-only previous or next link an aria-label, and mark the ellipsis aria-hidden="true".