Pagination

Navigate through large sets of data with numbered pages and controls.

import { component$, useSignal, useStyles$ } 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";

Features

Page number selection with keyboard navigation (arrows, home, end)
Dynamic pagination with customizable sibling count
First/Last page quick navigation
Ellipsis support for large page sets
WAI-ARIA compliant pagination controls
Controlled and uncontrolled page selection modes
Customizable ellipsis element
Disabled state handling
Page change event handlers
Automatic page range calculation
Focus management between page numbers
Boundary page number validation

Anatomy

Part	Description
<Pagination.Root>	Root pagination container component that provides context and handles page management
<Pagination.Page>	Individual page number button component
<Pagination.Next>	Next page navigation button component
<Pagination.Previous>	Previous page navigation button component
<Pagination.Ellipsis>	Renders an ellipsis item in the pagination

Examples

Basic Usage

The most basic pagination setup requires totalPages and pages props to define the range of pages available.

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 totalPages prop determines the total number of pages, while the pages array provides the actual page numbers to display. The currentPage prop sets which page is initially active.

Visual Features

Disabled State

Pages can be disabled to prevent interaction when at boundaries or based on conditions.

First Page (Previous disabled)

Last Page (Next disabled)

import { component$, useSignal } 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 isDisabled prop on Pagination.Page disables individual pages, while the disabled prop on Pagination.Root disables the entire pagination component.

Ellipsis Display

Customize how page gaps are displayed using ellipsis.

......

••••••

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>
  );
});

The ellipsis prop on Pagination.Root allows customization of the gap indicator between page numbers.

Add quick navigation to the start and end of the pagination range.

import { $, component$, useSignal, useStyles$ } 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"
      currentPage={1}
      totalPages={totalPagesSig.value}
      pages={paginationItems}
      onPageChange$={$((page: number) => {
        selectedPageSig.value = page;
      })}
    >
      <Pagination.Previous isFirst>First</Pagination.Previous>
      <Pagination.Previous>Previous</Pagination.Previous>

      {/* creates 10 pages */}
      {Array.from({ length: totalPagesSig.value }, (_, index) => {
        const uniqueKey = `page-${index}-${Date.now()}`;

        return (
          <Pagination.Page class="pagination-page" key={uniqueKey}>
            <span>{index + 1}</span>
          </Pagination.Page>
        );
      })}

      <Pagination.Next>Next</Pagination.Next>
      <Pagination.Next isLast>Last</Pagination.Next>
    </Pagination.Root>
  );
});

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

The isFirst and isLast props on Pagination.Previous and Pagination.Next respectively enable first/last page navigation.

Advanced Usage

Enable full keyboard control for accessibility.

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>
  );
});

Arrow keys navigate between pages, while Home/End keys jump to first/last pages. The component handles focus management automatically.

Custom Page Length

Control how many pages are displayed at once.

...

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>
  );
});

The totalPages prop determines the overall number of pages, while siblingCount controls how many adjacent pages are shown.

Sibling Count

Adjust how many pages appear on either side of the current page.

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>
  );
});

The siblingCount prop determines how many page numbers are visible before and after the current page.

Component State

Using Component State

The Pagination component offers several ways to control its state through props and events:

Current Page Control As shown in the page example above, you can set the initial page using the currentPage prop on Pagination.Root. For reactive control, use the bind:page prop which accepts a signal.
Total Pages The totalPages prop determines the total number of pages available for navigation, as demonstrated in the length example above.
Disabled State As shown in the disabled example above, the entire pagination can be disabled by setting the disabled prop on Pagination.Root. This will prevent all user interactions with the component.

State Interactions

Page Change Events The component provides an onPageChange$ prop to handle page navigation events:

<Pagination.Root
  totalPages={10}
  onPageChange$={(page: number) => {
    // Handle page change
    console.log(`Navigated to page ${page}`);
  }}
>
  {/* ... */}
</Pagination.Root>

Navigation Controls As demonstrated in the first-last example above, you can control navigation behavior using the isFirst and isLast props on the Previous and Next components respectively.
Sibling Pages The siblingCount prop controls how many page numbers are shown on either side of the current page, as shown in the siblings example above. This helps manage the pagination's visual state when dealing with large numbers of pages.
Custom Ellipsis As shown in the ellipsis example above, you can customize the appearance of truncated pages using the ellipsis prop on Pagination.Root. The pagination state is automatically managed to ensure:

Previous/Next buttons are disabled at boundaries
Current page is highlighted
Correct page range is displayed based on current selection
Proper ellipsis placement for large page counts

Based on the provided implementation and examples, I'll document the configuration options for the Pagination component.

Core Configuration

Page Management

The Pagination component requires essential configuration for managing page counts and navigation:

totalPages: Required number that sets the total available pages
currentPage: Optional initial page number (defaults to 1)
pages: Required array of page numbers to display As shown in the basic example above, these props work together to create the foundation of the pagination:

The currentPage will automatically be constrained between 1 and totalPages

Sibling Pages

The component supports configurable sibling pages through the siblingCount prop:

Controls how many page numbers appear on each side of the current page
Defaults to 1 if not specified
Must be a non-negative number As shown in the siblings example above, increasing siblingCount displays more adjacent page numbers.

Ellipsis Display

The ellipsis configuration determines how page gaps are displayed:

ellipsis: Optional custom element to replace the default "..." display
Automatically appears when there are too many pages to display
Intelligently positioned based on current page location As shown in the ellipsis example above, you can customize the ellipsis display.

Advanced Configuration

Controlled State

The component supports controlled state management through:

bind:page: Signal to control the current page externally
onPageChange$: Event handler called when page changes As shown in the page example above, these props enable external state control.

Additional navigation options can be configured:

isFirst: Boolean prop on <Pagination.Previous /> to jump to first page
isLast: Boolean prop on <Pagination.Next /> to jump to last page As shown in the first-last example above, these enable quick navigation to boundaries.

Disabled State

The pagination supports complete disabling:

disabled: Boolean prop to disable all pagination interactions
Automatically disables boundary navigation when at first/last page As shown in the disabled example above, this controls the interactive state of the entire component.

When disabled, all interactive elements receive the disabled attribute and appropriate ARIA states

API Reference

Inherits from: <div />

Props

Prop	Type	Default
totalPages	number	-
currentPage	number	-
"bind:page"	Signal<number \| 1>	-
onPageChange$	QRL<(page: number) => void>	-
disabled	boolean	-
pages	number[]	-
ellipsis	JSXChildren	-
siblingCount	number	-

Data Attributes

Attribute	Description
data-disabled	Indicates whether the pagination component is disabled

Data Attributes

Attribute	Description
data-index	Specifies the index of the pagination page
data-current	Indicates if this is the currently selected page

Inherits from: <div />

Inherits from: <button />

Accessibility

Keyboard Interactions

Key	Description
ArrowRight	When focus is on a page number button, moves focus to the next page number
ArrowLeft	When focus is on a page number button, moves focus to the previous page number
Home	When focus is on a page number button, moves focus to the first page number
End	When focus is on a page number button, moves focus to the last page number
Enter	When focus is on a page number button, selects that page number
Space	When focus is on the previous or next button, navigates to the previous or next page respectively

Pagination

Features

Anatomy

Examples

Basic Usage

Visual Features

Disabled State

First Page (Previous disabled)

Last Page (Next disabled)

Ellipsis Display

First and Last Navigation

Advanced Usage

Keyboard Navigation

Custom Page Length

Sibling Count

1 Sibling Count

2 Sibling Count

Component State

Using Component State

State Interactions

Core Configuration

Page Management

Sibling Pages

Ellipsis Display

Advanced Configuration

Controlled State

Navigation Controls

Disabled State

API Reference

Pagination Root

Props

Data Attributes

Pagination Page

Data Attributes

Pagination Ellipsis

Pagination Next

Pagination Previous

Accessibility

Keyboard Interactions