WARNING: This component is in

Draft

status. This means that it is still in development and may have bugs or missing features. It is not intended to be used in production. You may use it for testing purposes.

Pagination

✨ Features

Pagination ranges
Custom Arrows
Custom Button Labels
Fully Customizable

Interactive Example

pagessiblingCount

import { component$, useSignal, useStylesScoped$ } from '@builder.io/qwik';
import { Pagination } from '@qwik-ui/headless';
import { Toggle } from '@qwik-ui/styled';
import styles from '../index.css?inline';

export default component$(() => {
  useStylesScoped$(styles);

  const selectedPage = useSignal(1);
  const totalPages = useSignal(20);

  const hideNextButton = useSignal(false);
  const hidePrevButton = useSignal(false);
  const siblingCount = useSignal(1);

  return (
    <div class="mt-4 flex flex-col gap-6">
      <Pagination
        selectedPage={selectedPage.value}
        totalPages={totalPages.value}
        siblingCount={siblingCount.value}
        onPageChange$={(page) => {
          selectedPage.value = page;
        }}
        hidePrevButton={hidePrevButton.value}
        hideNextButton={hideNextButton.value}
        class="pagination-wrapper"
        selectedClass="pagination-selected-btn"
        defaultClass="pagination-btn"
        dividerClass="pagination-divider"
        prevButtonClass="prevNextButtons"
        nextButtonClass="prevNextButtons"
      />

      <hr />

      <div
        class="flex flex-col items-stretch gap-2"
        style={{
          width: '250px',
        }}
      >
        <label class="flex items-center justify-between gap-10">
          pages
          <input
            type="number"
            style={{
              width: '50px',
              background: 'transparent',
              textAlign: 'right',
            }}
            value={totalPages.value}
            onChange$={(e) => {
              totalPages.value = Number((e.target as HTMLInputElement).value);
            }}
          />
        </label>

        <label class="flex items-center justify-between gap-10">
          siblingCount
          <input
            type="number"
            style={{
              width: '50px',
              background: 'transparent',
              textAlign: 'right',
            }}
            value={siblingCount.value}
            onChange$={(e) => {
              siblingCount.value = Number((e.target as HTMLInputElement).value);
            }}
          />
        </label>

        <Toggle
          pressed={hideNextButton.value}
          onClick$={() => {
            hideNextButton.value = !hideNextButton.value;
          }}
        />

        <Toggle
          pressed={hidePrevButton.value}
          onClick$={() => {
            hidePrevButton.value = !hidePrevButton.value;
          }}
        />
      </div>
    </div>
  );
});

API

The Pagination component API provides a set of properties that allow you to customize the behavior and appearance of the pagination.

Here are the notable properties for this component:

Prop	Type	Description
`selectedPage`	`number`	Current Page Index (start from 1)
`totalPages`	`number`	The total of available pages
`onPageChange$`	`function`	Emitted when a button is clicked
`siblingCount`	`number`	set sibling items close to the selected value
`hidePrevButton`	`boolean`	hide the previous button
`hideNextButton`	`boolean`	hide the next button
`disabled`	`boolean`	disable mouse events
`customArrowTexts`	`ArrowLabels`	customize the PREVIOUS and NEXT button labels
`gap`	`string`	set the gap between items (i.e. '10px', '1rem', ...)
`class`	`string`	custom class for pagination wrapper
`defaultClass`	`string`	custom class for each pagination item
`selectedClass`	`string`	custom class for the selected item
`dividerClass`	`string`	custom class for the divider item
`prevButtonClass`	`string`	custom class for the Next button
`nextButtonClass`	`string`	custom class for the Next button

Basic Example

import { component$, useSignal, useStylesScoped$ } from '@builder.io/qwik';
import { Pagination } from '@qwik-ui/headless';
import styles from '../index.css?inline';

export default component$(() => {
  useStylesScoped$(styles);
  const selectedPage = useSignal(1);
  const totalPages = useSignal(10);

  return (
    <div class="mt-4 flex flex-col gap-6">
      <Pagination
        selectedPage={selectedPage.value}
        totalPages={totalPages.value}
        onPageChange$={(page) => {
          selectedPage.value = page;
        }}
        class="pagination-wrapper"
        selectedClass="pagination-selected-btn"
        defaultClass="pagination-btn"
        dividerClass="pagination-divider"
        prevButtonClass="prevNextButtons"
        nextButtonClass="prevNextButtons"
      />
    </div>
  );
});

Styling

import { component$, useSignal, useStylesScoped$ } from '@builder.io/qwik';
import { Pagination } from '@qwik-ui/headless';
import styles from '../index.css?inline';

export default component$(() => {
  useStylesScoped$(styles);
  const selectedPage = useSignal(1);
  const totalPages = useSignal(10);

  return (
    <div class="mt-4 flex flex-col gap-6">
      <Pagination
        selectedPage={selectedPage.value}
        totalPages={totalPages.value}
        onPageChange$={(page) => {
          selectedPage.value = page;
        }}
        class="border border-foreground p-2"
        defaultClass="border border-primary p-4"
        selectedClass="border bg-destructive p-4"
        dividerClass="bg-muted p-4"
      />

      <Pagination
        selectedPage={selectedPage.value}
        totalPages={totalPages.value}
        onPageChange$={(page) => {
          selectedPage.value = page;
        }}
        class="border border-foreground p-2"
        defaultClass="bg-primary w-8 h-8"
        selectedClass="bg-destructive w-8 h-8"
        dividerClass="bg-muted h-8 px-2"
      />

      <Pagination
        selectedPage={selectedPage.value}
        totalPages={totalPages.value}
        onPageChange$={(page) => {
          selectedPage.value = page;
        }}
        class="flex flex-col items-center gap-2 border border-primary"
        defaultClass=""
        selectedClass=""
        dividerClass=""
      />
    </div>
  );
});

Custom Button Labels

import { component$, useSignal, useStylesScoped$ } from '@builder.io/qwik';
import { Pagination } from '@qwik-ui/headless';
import styles from '../index.css?inline';

export default component$(() => {
  useStylesScoped$(styles);
  const selectedPage = useSignal(1);
  const totalPages = useSignal(10);

  return (
    <div class="mt-4 flex flex-col gap-6">
      <Pagination
        selectedPage={selectedPage.value}
        totalPages={totalPages.value}
        onPageChange$={(page) => {
          selectedPage.value = page;
        }}
        customArrowTexts={{ previous: 'LEFT', next: 'RIGHT' }}
        class="pagination-wrapper"
        selectedClass="pagination-selected-btn"
        defaultClass="pagination-btn"
        dividerClass="pagination-divider"
        prevButtonClass="prevNextButtons"
        nextButtonClass="prevNextButtons"
      />
    </div>
  );
});

Custom Arrows

import { component$, useSignal, useStylesScoped$ } from '@builder.io/qwik';
import { Pagination } from '@qwik-ui/headless';
import styles from '../index.css?inline';

export default component$(() => {
  useStylesScoped$(styles);
  const selectedPage = useSignal(5);
  const totalPages = useSignal(20);

  return (
    <div class="mt-4 flex flex-col gap-6">
      <Pagination
        selectedPage={selectedPage.value}
        totalPages={totalPages.value}
        onPageChange$={(page) => {
          selectedPage.value = page;
        }}
        class="pagination-wrapper"
        selectedClass="pagination-selected-btn"
        defaultClass="pagination-btn"
        dividerClass="pagination-divider"
        prevButtonClass="prevNextButtons"
        nextButtonClass="prevNextButtons"
      >
        <span q:slot="prefix"> 👈 </span>
        <span q:slot="suffix"> 👉 </span>
      </Pagination>
    </div>
  );
});

Hide Next/Prev Buttons

import { component$, useSignal, useStylesScoped$ } from '@builder.io/qwik';
import { Pagination } from '@qwik-ui/headless';
import styles from '../index.css?inline';

export default component$(() => {
  useStylesScoped$(styles);
  const selectedPage = useSignal(1);
  const totalPages = useSignal(10);

  return (
    <div class="mt-4 flex flex-col gap-6">
      <Pagination
        selectedPage={selectedPage.value}
        totalPages={totalPages.value}
        onPageChange$={(page) => {
          selectedPage.value = page;
        }}
        hidePrevButton={true}
        hideNextButton={true}
        class="pagination-wrapper"
        selectedClass="pagination-selected-btn"
        defaultClass="pagination-btn"
        dividerClass="pagination-divider"
        prevButtonClass="prevNextButtons"
        nextButtonClass="prevNextButtons"
      />
    </div>
  );
});

Disabled

import { component$, useSignal, useStylesScoped$ } from '@builder.io/qwik';
import { Pagination } from '@qwik-ui/headless';
import styles from '../index.css?inline';

export default component$(() => {
  useStylesScoped$(styles);
  const selectedPage = useSignal(1);
  const totalPages = useSignal(10);

  return (
    <div class="mt-4 flex flex-col gap-6">
      <Pagination
        selectedPage={selectedPage.value}
        totalPages={totalPages.value}
        disabled
        onPageChange$={(page) => {
          selectedPage.value = page;
        }}
        class="pagination-wrapper"
        selectedClass="pagination-selected-btn"
        defaultClass="pagination-btn"
        dividerClass="pagination-divider"
        prevButtonClass="prevNextButtons"
        nextButtonClass="prevNextButtons"
      />
    </div>
  );
});