# Pagination

Pagination with page navigation, next and previous links.

Source: https://webjs.dev/ui/docs/components/pagination

```ts
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>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add pagination
```

### Copy and paste the following code into your project.

````ts title="components/ui/pagination.ts"
/**
 * 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

```ts
import {
  paginationClass,
  paginationContentClass,
  paginationLinkClass,
  paginationPreviousClass,
  paginationNextClass,
  paginationEllipsisClass,
} from '#components/ui/pagination.ts';
```

```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:

```text
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.

```ts
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>
  `;
}
```

## Icons Only

Use just the previous and next buttons without page numbers. This is useful for data tables with a rows per page selector.

```ts
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>
  `;
}
```

## 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.

```ts
<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](https://webjs.dev/ui/docs/rtl).

```ts
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>
  `;
}
```

## 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"`.

| Helper | Applies to |
| --- | --- |
| `paginationClass()` | The `<nav>`. |
| `paginationContentClass()` | The `<ul>`. |
| `paginationLinkClass()` | A page `<a>`. |
| `paginationPreviousClass()` | The previous page `<a>`. |
| `paginationNextClass()` | The next page `<a>`. |
| `paginationEllipsisClass()` | The ellipsis. |

### paginationLinkClass

| Option | Type | Default |
| --- | --- | --- |
| `isActive` | `boolean` | `false` |
| `size` | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | `"icon"` |
