Pagination

Page navigation with smart ellipses, jump controls and a quick-jump input.

"use client";

import { Pagination } from "astralis-ui";

export function PaginationDemo() {
  return (
    <Pagination totalPages={10} defaultPage={3}>
      <Pagination.List>
        <Pagination.Prev />
        <Pagination.Pages />
        <Pagination.Next />
      </Pagination.List>
    </Pagination>
  );
}

Import#

import { Pagination } from "astralis-ui";
// Pagination.List, .Pages, .Item, .Prev, .Next,
// .First, .Last, .PageText, .Jumper

Variants#

solid

outline

subtle

plain

"use client";

import { Pagination, Text, VStack } from "astralis-ui";

const variants = ["solid", "outline", "subtle", "plain"] as const;

export function PaginationVariants() {
  return (
    <VStack gap="5" alignItems="start">
      {variants.map((variant) => (
        <VStack key={variant} gap="1" alignItems="start">
          <Text as="span" size="xs" color="muted">{variant}</Text>
          <Pagination totalPages={5} defaultPage={2} variant={variant} size="sm">
            <Pagination.List>
              <Pagination.Prev />
              <Pagination.Pages />
              <Pagination.Next />
            </Pagination.List>
          </Pagination>
        </VStack>
      ))}
    </VStack>
  );
}

Everything on#

Derive the page count from an item count + pageSize, pin boundary pages, and compose every control — Pages handles the ellipses automatically.

"use client";

import { Pagination } from "astralis-ui";

export function PaginationFull() {
  return (
    /* Derive pages from an item count, pin boundaries, and add every control. */
    <Pagination count={195} pageSize={10} defaultPage={7} colorScheme="teal">
      <Pagination.List>
        <Pagination.First />
        <Pagination.Prev />
        <Pagination.Pages siblings={1} boundaryCount={1} />
        <Pagination.Next />
        <Pagination.Last />
        <Pagination.Jumper />
      </Pagination.List>
    </Pagination>
  );
}

Controlled#

page + onPageChange for server-driven data — the usual case.

Fetching results for page 1…

"use client";

import { useState } from "react";
import { Pagination, Text, VStack } from "astralis-ui";

export function PaginationControlled() {
  const [page, setPage] = useState(1);

  return (
    <VStack gap="3">
      <Pagination totalPages={8} page={page} onPageChange={setPage} variant="subtle">
        <Pagination.List>
          <Pagination.Prev />
          <Pagination.Pages />
          <Pagination.Next />
          <Pagination.PageText />
        </Pagination.List>
      </Pagination>
      <Text size="sm" color="muted">
        Fetching results for page {page}…
      </Text>
    </VStack>
  );
}

Props#

Prop	Type	Default	Description
`page · defaultPage · onPageChange`	`number · number · (page: number) => void`	`— · 1 · —`	Controlled / initial page, and the change callback.
`totalPages`	`number`	—	Explicit page count — use this OR count + pageSize.
`count · pageSize`	`number · number`	`— · 10`	Total items; the page count is derived.
`variant`	`"solid" \| "outline" \| "subtle" \| "plain"`	`"solid"`	Page-button styling; the active page carries the accent.
`size`	`"xs" \| "sm" \| "md" \| "lg"`	`"md"`	Button sizing.
`rounded`	`"none" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "full"`	`"md"`	Button corner radius.
`colorScheme`	`"brand" \| "gray" \| … (all 11 schemes)`	`"brand"`	Active page and focus-ring hue.
`disabled`	`boolean`	`false`	Disables the whole control.

Parts#

Prop	Type	Default	Description
`Pagination.Pages`	`siblings?: number · boundaryCount?: number`	`1 · 1`	Page buttons around the current page and pinned at the ends, with ellipses between.
`Pagination.Prev / Next / First / Last`	`icon?: ReactNode`	—	Step and jump buttons; default chevron icons.
`Pagination.PageText`	`format?: (state) => ReactNode`	`"Page 3 of 8"`	Live-region readout of the current state.
`Pagination.Jumper`	`label?: ReactNode`	`"Go to"`	Number input that jumps straight to a page.
`Pagination.Item`	`page: number`	—	A single page button, for fully manual layouts.

Keyboard#

Key	Action
`Tab`	Move between the page and prev/next buttons
`Enter` / `Space`	Activate the focused button
`Enter` in the Jumper	Jump to the typed page (clamped to range)

Accessibility#

Renders a nav landmark labeled "Pagination"; the active page carries aria-current="page".
PageText is an aria-live region, so page changes are announced.
The Jumper input has an accessible label and clamps to valid pages.