# Pagination

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

## Usage

Use as a coordinator around `ComboBox`.
```svelte
<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.

```svelte
<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

| Name | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` | - | Custom pagination content; receives value and variant |
| `value` | `number` | `1` | Bindable current page |
| `min` | `number` | `1` | First page |
| `max` | `number` | - | Last page; defaults to `max(min, value)` |
| `options` | `number[]` | - | Shortcut page numbers shown by the embedded `ComboBox` |
| `top` | `Snippet` | - | FIRST button content; receives value and variant |
| `left` | `Snippet` | - | PREV button content; receives value and variant |
| `right` | `Snippet` | - | NEXT button content; receives value and variant |
| `bottom` | `Snippet` | - | LAST button content; receives value and variant |
| `ariaLabel` | `string` | `"Pagination"` | Accessible label for the nav landmark |
| `buttonLabels` | `PaginationLabel` | - | Accessible labels for the buttons; defaults First/Previous/Next/Last page |
| `comboBox` | `ComboBoxProps` | - | Config bag spread into the embedded `ComboBox`; uses the flat inner-prop shape and is ignored when `children` is supplied |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Variant |
Other `<nav>` attributes are passed to `<nav>` via rest props; `class` is merged onto the root.

## Styling

To learn more, see [Styling](/docs/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](/docs/combo-box) 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](/docs/concepts) for the library's approach.

## Exports

### Types

```ts
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

**Code**

```svelte src=PaginationBasic.svelte
<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

**Code**

```svelte src=PaginationPract.svelte
<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>
```