Pagination

A component that enables users to navigate through multiple pages of content with numbered buttons and previous/next controls.

import { $, component$, useSignal, useStyles$, useTask$ } from "@builder.io/qwik";
import { Pagination } from "@kunai-consulting/qwik";

export default component$(() => {
  useStyles$(styles);
  const selectedPageSig = useSignal(1);
  const totalPagesSig = useSignal(10);
  const paginationItems = [...Array(totalPagesSig.value)].map((_, index) => index + 1);

  return (
    <Pagination.Root
      class="pagination-root"
      totalPages={totalPagesSig.value}
      currentPage={selectedPageSig.value}
      pages={paginationItems}
      siblingCount={totalPagesSig.value}
      ellipsis="..."
    >
      <Pagination.Previous class="pagination-previous">Prev</Pagination.Previous>
      {paginationItems.map((item, index) => {
        const uniqueKey = `page-${index}-${Date.now()}`;
        return (
          <Pagination.Page class="pagination-page" key={uniqueKey}>
            <span>{item}</span>
          </Pagination.Page>
        );
      })}
      <Pagination.Next class="pagination-next">Next</Pagination.Next>
    </Pagination.Root>
  );
});

import styles from "./pagination.css?inline";

Basic Usage

To create a pagination component, use the Pagination.Root component to wrap Pagination.Page, Pagination.Previous, and Pagination.Next components.

import { component$, useSignal } from "@builder.io/qwik";
import { Pagination } from "@kunai-consulting/qwik";

export default component$(() => {
  const selectedPageSig = useSignal(1);
  const totalPagesSig = useSignal(5);
  const paginationItems = [...Array(totalPagesSig.value)].map((_, index) => index + 1);

  return (
    <Pagination.Root
      class="pagination-root"
      totalPages={totalPagesSig.value}
      currentPage={selectedPageSig.value}
      pages={paginationItems}
      siblingCount={1}
    >
      <Pagination.Previous class="pagination-previous">Prev</Pagination.Previous>
      {paginationItems.map((item) => (
        <Pagination.Page class="pagination-page" key={`page-${item}`}>
          {item}
        </Pagination.Page>
      ))}
      <Pagination.Next class="pagination-next">Next</Pagination.Next>
    </Pagination.Root>
  );
});

The pagination component includes Previous and Next buttons for easy navigation between pages.

Pagination.Previous - Navigates to the previous page
Pagination.Next - Navigates to the next page

import { component$, useSignal } from "@builder.io/qwik";
import { Pagination } from "@kunai-consulting/qwik";

export default component$(() => {
  const selectedPageSig = useSignal(1);
  const totalPagesSig = useSignal(3);
  const paginationItems = [...Array(totalPagesSig.value)].map((_, index) => index + 1);

  return (
    <Pagination.Root
      class="pagination-root"
      totalPages={totalPagesSig.value}
      currentPage={selectedPageSig.value}
      pages={paginationItems}
    >
      <Pagination.Previous class="pagination-previous">← Previous</Pagination.Previous>

      {paginationItems.map((item) => (
        <Pagination.Page key={`page-${item}`} class="pagination-page">
          {item}
        </Pagination.Page>
      ))}

      <Pagination.Next class="pagination-next">Next →</Pagination.Next>
    </Pagination.Root>
  );
});

Custom Length

The pagination automatically adjusts based on the totalPages prop provided to Pagination.Root.

...

import { component$, useSignal } from "@builder.io/qwik";
import { Pagination } from "@kunai-consulting/qwik";

export default component$(() => {
  const selectedPageSig = useSignal(1);
  const totalPagesSig = useSignal(20); // Using more pages to demonstrate length
  const paginationItems = [...Array(totalPagesSig.value)].map((_, index) => index + 1);

  return (
    <Pagination.Root
      class="pagination-root"
      totalPages={totalPagesSig.value}
      currentPage={selectedPageSig.value}
      pages={paginationItems}
      siblingCount={2}
      ellipsis="..."
    >
      <Pagination.Previous class="pagination-previous">Previous</Pagination.Previous>
      {paginationItems.map((item) => (
        <Pagination.Page class="pagination-page" key={`page-${item}`}>
          {item}
        </Pagination.Page>
      ))}
      <Pagination.Next class="pagination-next">Next</Pagination.Next>
    </Pagination.Root>
  );
});

Sibling Count

Control how many page numbers appear before and after the current page using the siblingCount prop.

1 Sibling Count

......

2 Sibling Count

......

import { component$, useSignal } from "@builder.io/qwik";
import { Pagination } from "@kunai-consulting/qwik";

export default component$(() => {
  const selectedPageSig = useSignal(5); // Start in middle to show siblings
  const totalPagesSig = useSignal(10);
  const paginationItems = [...Array(totalPagesSig.value)].map((_, index) => index + 1);

  return (
    <div class="flex flex-col gap-4">
      {/* Small sibling count */}
      <h2>1 Sibling Count</h2>
      <Pagination.Root
        class="pagination-root"
        totalPages={totalPagesSig.value}
        currentPage={selectedPageSig.value}
        pages={paginationItems}
        siblingCount={1}
        ellipsis="..."
      >
        <Pagination.Previous class="pagination-previous">Previous</Pagination.Previous>
        {paginationItems.map((item) => (
          <Pagination.Page class="pagination-page" key={`sibling-1-page-${item}`}>
            {item}
          </Pagination.Page>
        ))}
        <Pagination.Next class="pagination-next">Next</Pagination.Next>
      </Pagination.Root>

      {/* Large sibling count */}
      <h2>2 Sibling Count</h2>
      <Pagination.Root
        class="pagination-root"
        totalPages={totalPagesSig.value}
        currentPage={selectedPageSig.value}
        pages={paginationItems}
        siblingCount={2}
        ellipsis="..."
      >
        <Pagination.Previous class="pagination-previous">Previous</Pagination.Previous>
        {paginationItems.map((item) => (
          <Pagination.Page class="pagination-page" key={`sibling-2-page-${item}`}>
            {item}
          </Pagination.Page>
        ))}
        <Pagination.Next class="pagination-next">Next</Pagination.Next>
      </Pagination.Root>
    </div>
  );
});

Ellipsis

When there are many pages, ellipsis (...) is automatically shown to indicate skipped page numbers. You can customize the ellipsis character using the ellipsis prop.

......

••••••

import { component$, useSignal } from "@builder.io/qwik";
import { Pagination } from "@kunai-consulting/qwik";

export default component$(() => {
  const selectedPageSig = useSignal(5); // Middle page to show ellipsis on both sides
  const totalPagesSig = useSignal(10);
  const paginationItems = [...Array(totalPagesSig.value)].map((_, index) => index + 1);

  return (
    <div class="flex flex-col gap-4">
      {/* Default dots ellipsis */}
      <Pagination.Root
        class="pagination-root"
        totalPages={totalPagesSig.value}
        currentPage={selectedPageSig.value}
        pages={paginationItems}
        siblingCount={1}
        ellipsis="..."
      >
        <Pagination.Previous class="pagination-previous">Previous</Pagination.Previous>
        {paginationItems.map((item) => (
          <Pagination.Page class="pagination-page" key={`dots-page-${item}`}>
            {item}
          </Pagination.Page>
        ))}
        <Pagination.Next class="pagination-next">Next</Pagination.Next>
      </Pagination.Root>

      {/* Custom ellipsis */}
      <Pagination.Root
        class="pagination-root"
        totalPages={totalPagesSig.value}
        currentPage={selectedPageSig.value}
        pages={paginationItems}
        siblingCount={1}
        ellipsis="•••"
      >
        <Pagination.Previous class="pagination-previous">Previous</Pagination.Previous>
        {paginationItems.map((item) => (
          <Pagination.Page class="pagination-page" key={`custom-page-${item}`}>
            {item}
          </Pagination.Page>
        ))}
        <Pagination.Next class="pagination-next">Next</Pagination.Next>
      </Pagination.Root>
    </div>
  );
});

Disabled State

The pagination component handles disabled states:

Previous button is disabled on the first page
Next button is disabled on the last page
Current page button is disabled

First Page (Previous disabled)

Last Page (Next disabled)

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Pagination } from "@kunai-consulting/qwik";

export default component$(() => {
  // Examples for first page and last page
  const firstPageSig = useSignal(1);
  const lastPageSig = useSignal(5);
  const totalPagesSig = useSignal(5);
  const paginationItems = [...Array(totalPagesSig.value)].map((_, index) => index + 1);

  return (
    <div class="flex flex-col gap-4">
      {/* First page - Previous button disabled */}
      <h2>First Page (Previous disabled)</h2>
      <Pagination.Root
        class="pagination-root"
        totalPages={totalPagesSig.value}
        currentPage={firstPageSig.value}
        pages={paginationItems}
      >
        <Pagination.Previous class="pagination-previous disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none">
          Previous
        </Pagination.Previous>
        {paginationItems.map((item) => (
          <Pagination.Page
            class="pagination-page disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none"
            key={`first-page-${item}`}
            isDisabled={item === firstPageSig.value}
          >
            {item}
          </Pagination.Page>
        ))}
        <Pagination.Next class="pagination-next disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none">
          Next
        </Pagination.Next>
      </Pagination.Root>

      {/* Last page - Next button disabled */}
      <h2>Last Page (Next disabled)</h2>
      <Pagination.Root
        class="pagination-root"
        totalPages={totalPagesSig.value}
        currentPage={lastPageSig.value}
        pages={paginationItems}
      >
        <Pagination.Previous class="pagination-previous disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none">
          Previous
        </Pagination.Previous>
        {paginationItems.map((item) => (
          <Pagination.Page
            class="pagination-page disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none"
            key={`last-page-${item}`}
            isDisabled={item === lastPageSig.value}
          >
            {item}
          </Pagination.Page>
        ))}
        <Pagination.Next class="pagination-next disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none">
          Next
        </Pagination.Next>
      </Pagination.Root>
    </div>
  );
});

The pagination component supports keyboard navigation:

Left/Right arrows to move between pages
Home key to jump to first page
End key to jump to last page

Keyboard Navigation:← Previous page|→ Next pageHome First page|End Last page

import { component$, useSignal } from "@builder.io/qwik";
import { Pagination } from "@kunai-consulting/qwik";

export default component$(() => {
  const selectedPageSig = useSignal(3);
  const totalPagesSig = useSignal(5);
  const paginationItems = [...Array(totalPagesSig.value)].map((_, index) => index + 1);

  return (
    <div class="flex flex-col gap-4">
      <p class="text-sm text-gray-600 space-y-2">
        <span class="block font-medium">Keyboard Navigation:</span>
        <span class="block">
          <kbd class="px-2 py-1 bg-gray-100 rounded">←</kbd> Previous page
          <span class="mx-2">|</span>
          <kbd class="px-2 py-1 bg-gray-100 rounded">→</kbd> Next page
        </span>
        <span class="block">
          <kbd class="px-2 py-1 bg-gray-100 rounded">Home</kbd> First page
          <span class="mx-2">|</span>
          <kbd class="px-2 py-1 bg-gray-100 rounded">End</kbd> Last page
        </span>
      </p>

      <Pagination.Root
        class="pagination-root"
        totalPages={totalPagesSig.value}
        currentPage={selectedPageSig.value}
        pages={paginationItems}
      >
        <Pagination.Previous
          class="pagination-previous disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none"
          aria-label="Go to previous page"
        >
          Previous
        </Pagination.Previous>

        {paginationItems.map((item) => (
          <Pagination.Page
            class="pagination-page disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none"
            key={`page-${item}`}
            aria-label={`Page ${item}`}
          >
            {item}
          </Pagination.Page>
        ))}

        <Pagination.Next
          class="pagination-next disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none"
          aria-label="Go to next page"
        >
          Next
        </Pagination.Next>
      </Pagination.Root>
    </div>
  );
});

Accessibility

The pagination component is built with accessibility in mind and follows WCAG guidelines:

ARIA Attributes

Uses aria-label="pagination" on the navigation container
Each page button includes aria-current="page" for the active page
Previous/Next buttons have descriptive aria-label values
Disabled buttons include aria-disabled="true"

Pagination

Basic Usage

Navigation Controls

Custom Length

Sibling Count

1 Sibling Count

2 Sibling Count

Ellipsis

Disabled State

First Page (Previous disabled)

Last Page (Next disabled)

Keyboard Navigation

Accessibility

ARIA Attributes