Pagination

A page navigator that coordinates first, previous, next, last, and page input controls.

Usage

Use as a coordinator around ComboBox.

<Pagination comboBox={{ placeholder: "Page" }} />

<Pagination>
  <ComboBox />
</Pagination>

Anatomy

The class attribute values represent part names. Other attributes represent their corresponding props. An embedded ComboBox renders between the left and right buttons unless children is supplied.

<nav class="whole" aria-label>
  <button class="top" type="button" aria-label aria-disabled>{top}</button>
  <button class="left" type="button" aria-label aria-disabled>{left}</button>
  {#if children}{children}{:else}<ComboBox />{/if}
  <button class="right" type="button" aria-label aria-disabled>{right}</button>
  <button class="bottom" type="button" aria-label aria-disabled>{bottom}</button>
</nav>

• The page commits on ComboBox blur, Enter, and option select; invalid input reverts and out-of-range input clamps.
• Buttons use aria-disabled, stay focusable at bounds, and suppress their action while at-bound.
• Part names map by position: TOP=first, LEFT=prev, RIGHT=next, BOTTOM=last.
• Embedded ComboBox is wired through context; comboBox is ignored when children is supplied.
• onchange fires a native change Event after user-initiated page changes (nav buttons or ComboBox commits); read the new page from bound value. Programmatic value changes and bound clamping do not fire it.
• The default shortcut list is centered on the current page. A caller-provided options list can follow the page with bind:value={page} and const opts = $derived(...); no change event is needed.

Props

Other <nav> attributes are passed to <nav> via rest props; class is merged onto the root.

Styling

To learn more, see Styling.

Variant Management

The FIRST and PREV buttons render with VARIANT.INACTIVE while value is at min; NEXT and LAST render with VARIANT.INACTIVE while value is at max.

Default Class Name

svs-pagination

Behavior

• The page commits on ComboBox blur, Enter, and option select; invalid input reverts and out-of-range input clamps.
• Buttons use aria-disabled, stay focusable at bounds, and suppress their action while at-bound.
• Part names map by position: TOP=first, LEFT=prev, RIGHT=next, BOTTOM=last.
• Embedded ComboBox is wired through context; comboBox is ignored when children is supplied.
• onchange fires a native change Event after user-initiated page changes (nav buttons or ComboBox commits); read the new page from bound value. Programmatic value changes and bound clamping do not fire it.
• The default shortcut list is centered on the current page. A caller-provided options list can follow the page with bind:value={page} and const opts = $derived(...); no change event is needed.

Accessibility

ARIA Roles and Attributes

The component applies these automatically:

• Navigation (whole <nav>): aria-label, defaulting to "Pagination" and overridable with ariaLabel.
• Boundary buttons (top, left, right, bottom <button>): aria-label from buttonLabels.top, buttonLabels.left, buttonLabels.right, or buttonLabels.bottom, and aria-disabled while the button is at its first-page or last-page boundary.
• Button icons (<svg>): aria-hidden="true" and focusable="false".

The boundary buttons stay focusable at their bounds and suppress their action instead of leaving the tab order. When the jump control is rendered by the default ComboBox, see ComboBox for its ARIA attributes and keyboard behavior.

Standards Basis

Pagination's boundary controls are native <button> elements, so keyboard and assistive-technology support follows the browser standard for button controls. See the Concepts standards-first guidance for the library's approach.

Exports

Types

type PaginationLabel = { top?: string; left?: string; right?: string; bottom?: string };
interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, "children" | "aria-label"> {
  children?: Snippet<[number, string]>; // Snippet<[value,variant]>
  value?: number; // bindable; current page (default 1)
  min?: number; // first page (default 1)
  max?: number; // last page (default = max(min, value))
  options?: number[]; // shortcut list shown in the ComboBox
  top?: Snippet<[number, string]>; // Snippet<[value,variant]>; FIRST button content
  left?: Snippet<[number, string]>; // Snippet<[value,variant]>; PREV button content
  right?: Snippet<[number, string]>; // Snippet<[value,variant]>; NEXT button content
  bottom?: Snippet<[number, string]>; // Snippet<[value,variant]>; LAST button content
  ariaLabel?: string; // ("Pagination")
  buttonLabels?: PaginationLabel; // ({top:"First page",left:"Previous page",right:"Next page",bottom:"Last page"})
  comboBox?: Omit<ComboBoxProps, ComboBoxReqdProps | ComboBoxBindProps | "options" | "variant" | "styling">;
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  // other nav attributes are passed to <nav> via ...rest; `class` is merged onto root
}
type PaginationReqdProps = never;
type PaginationBindProps = "value";

Others

No additional exports are available.

Examples

The example code uses Tailwind CSS along with SVSClass.

Basic

<script lang="ts">
  import { Pagination } from "svseeds";

  let page = $state(4);
  const childStyle = {
    whole: "mx-1 w-12",
    main: "px-2 py-1 w-full rounded-md border text-center outline-hidden",
    bottom: "w-full bg-white dark:bg-black",
    label: {
      base: "px-2 text-center",
      active: "bg-gray-400",
    },
  };
  const childProps = {
    placeholder: "Page",
    styling: childStyle,
  };
  const arrowStyle = {
    base: "p-1 stroke-0 size-8 rounded-md border",
    inactive: "opacity-40",
  };
  const styling = {
    whole: "flex items-center gap-1",
    top: arrowStyle,
    left: arrowStyle,
    right: arrowStyle,
    bottom: arrowStyle,
  };
  const myProps = {
    min: 1,
    max: 12,
    comboBox: childProps,
    styling,
  };
</script>

<div class="flex flex-col items-center gap-3">
  <Pagination bind:value={page} {...myProps} />
  <div class="text-sm">Page {page} of 12</div>
</div>

With Interactive Variant

<script lang="ts">
  import { Pagination, ComboBox } from "svseeds";
  import ChevronFirst from "@lucide/svelte/icons/chevron-first";
  import ChevronLeft from "@lucide/svelte/icons/chevron-left";
  import ChevronRight from "@lucide/svelte/icons/chevron-right";
  import ChevronLast from "@lucide/svelte/icons/chevron-last";

  let { variant = $bindable() } = $props();
  let page = $state(5);
  const variantStyle = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "opacity-30",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const childStyle = {
    whole: "mx-1 w-12",
    main: {
      base: "px-2 py-1 w-full rounded-md border text-center outline-hidden",
      ...variantStyle,
    },
    bottom: "w-full bg-white dark:bg-black",
    label: {
      base: "px-2 text-center",
      active: "bg-gray-400",
    },
  };
  const childProps = {
    placeholder: "Page",
    styling: childStyle,
  };
  const arrowStyle = {
    base: "size-8 rounded-md border",
    ...variantStyle,
  };
  const styling = {
    whole: "flex items-center gap-1",
    top: arrowStyle,
    left: arrowStyle,
    right: arrowStyle,
    bottom: arrowStyle,
  };
  const myProps = {
    min: 1,
    max: 9,
    styling,
  };
</script>

<div class="flex flex-col items-center gap-3">
  <Pagination bind:value={page} {variant} {...myProps}>
    <ComboBox {...childProps} />
    {#snippet top()}<ChevronFirst class="size-full" />{/snippet}
    {#snippet left()}<ChevronLeft class="size-full" />{/snippet}
    {#snippet right()}<ChevronRight class="size-full" />{/snippet}
    {#snippet bottom()}<ChevronLast class="size-full" />{/snippet}
  </Pagination>
  <div class="text-sm">Page {page} of 9</div>
</div>