Skip to content
WebJs
Menu

Pagination with page navigation, next and previous links.

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

pnpm dlx @webjsdev/ui add pagination

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

HelperApplies 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

OptionTypeDefault
isActivebooleanfalse
size"default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg""icon"