Pagination

Plain `nav > ul > li` markup. `PaginationLink` renders this library's `Button` with `asChild` around an `<a>`, so the anchor gets the button's variant, size, focus ring, press feedback and disabled guard while staying a link; the anchor sets its own `data-slot="pagination-link"`, which overrides the button's slot through Radix Slot's prop merge (child props win). `className` goes to `Button`, where `cn` merges it last so the caller wins. The active state adds `aria-current` plus `data-active` for styling hooks. Icons are inline 16-unit `currentColor` SVGs. Compared with the source: `buttonVariants`/`cva` is replaced by composing `Button asChild` (our `Button` exports no variants helper), lucide icons are inline SVGs, a `disabled` prop is added for first/last pages, and the ellipsis label is audible and configurable.

**Pebble (2026-11-03).** The outline-button active state is replaced by a moving indicator. The file is now `"use client"`: `Pagination` wraps its `nav` in `MotionConfig reducedMotion="user"` and a `LayoutGroup` keyed by `useId()` (so two pagers on one page never trade indicators), and the active `PaginationLink` renders a `motion.span` with `layoutId="pagination-indicator"`, `absolute inset-0 -z-10` inside an `isolate` link, which springs (`stiffness 420, damping 32, mass 0.8`) to the newly active page. In `plain` it is the lit key (`from-key-top to-key-bottom`, `ring-key-edge`, `--key-shine` + `--elevation-sm`), whose gradient flips to `--key-press` on `group-active/page`; in `well` it is a `bg-card` pebble with `ring-hairline shadow-raised-xs inset-shadow-highlight` (`dark:bg-foreground/12` so it lifts off the dark well) that flattens on press. `PaginationContent` takes `variant` and shares it through context, so links and the ellipsis pick `size-8` in the well. Numbers are 13 px `tabular-nums` in `text-muted-foreground`; Previous/Next are `text-foreground` with chevrons that nudge 2 px outward on hover (mirrored in RTL).

<!-- PEBBLE-LICENSE -->

registry/nav/pagination/pagination.tsx

"use client";

/* PEBBLE-LICENSE
Built by Pebble. Component: pagination.

First-party license: MIT

The following first-party terms apply only to original Pebble material.

MIT License

Copyright (c) 2026 Praxys Solutions LLC (Pebble)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

THIRD-PARTY NOTICES
These notices apply to identified upstream portions; Pebble terms do not replace or narrow their rights.

Upstream: https://raw.githubusercontent.com/shadcn-ui/ui/main/LICENSE.md
MIT License

Copyright (c) 2023 shadcn

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
END PEBBLE-LICENSE */

import * as React from "react";
import { LayoutGroup, MotionConfig, motion } from "motion/react";

import { cn } from "@/lib/utils";
import { Button, type ButtonProps } from "@/registry/button/button/button";

const spring = { type: "spring", stiffness: 420, damping: 32, mass: 0.8 } as const;

type PaginationVariant = "plain" | "well";
const PaginationContext = React.createContext<{ variant: PaginationVariant }>({
  variant: "plain",
});

export function Pagination({
  "aria-label": ariaLabel,
  className,
  ...props
}: React.ComponentProps<"nav">) {
  // One layout group per pagination, so two on a page never trade indicators.
  const id = React.useId();
  return (
    <MotionConfig reducedMotion="user">
      <LayoutGroup id={id}>
        <nav
          data-slot="pagination"
          aria-label={ariaLabel ?? "Pagination"}
          className={cn("mx-auto flex w-full max-w-full min-w-0 justify-center", className)}
          {...props}
        />
      </LayoutGroup>
    </MotionConfig>
  );
}

const contentVariants = {
  plain: "gap-1",
  // A recessed well; the current page is a raised pebble sitting in it.
  well: "gap-0.5 rounded-lg bg-muted p-1 inset-shadow-[0_1px_2px_var(--hairline)]",
} as const;

export type PaginationContentProps = React.ComponentProps<"ul"> & {
  /** `plain` (default): the current page is the lit key. `well`: a recessed track with a raised current page. */
  variant?: PaginationVariant;
};

export function PaginationContent({
  variant = "plain",
  className,
  ...props
}: PaginationContentProps) {
  return (
    <PaginationContext.Provider value={{ variant }}>
      <ul
        data-slot="pagination-content"
        data-variant={variant}
        // Wraps rather than overflowing when the row is wider than the screen.
        className={cn(
          "flex flex-row flex-wrap items-center justify-center",
          contentVariants[variant],
          className,
        )}
        {...props}
      />
    </PaginationContext.Provider>
  );
}

export function PaginationItem(props: React.ComponentProps<"li">) {
  return <li data-slot="pagination-item" {...props} />;
}

export type PaginationLinkProps = React.ComponentProps<"a"> & {
  /** The page this link points to is the one being shown. */
  isActive?: boolean;
  /** Button size; page numbers are square `icon` buttons. */
  size?: ButtonProps["size"];
  /** Block the link (e.g. Previous on the first page): aria-disabled, out of tab order. */
  disabled?: boolean;
};

const indicatorClass = {
  // The lit key, which flips its gradient and sinks while the link is pressed.
  plain:
    "bg-linear-to-b from-key-top to-key-bottom ring-1 ring-key-edge shadow-[var(--key-shine),var(--elevation-sm)] group-active/page:bg-linear-to-t group-active/page:shadow-[var(--key-press)]",
  // In dark mode the pebble steps up in lightness so it still sits above the well.
  well: "bg-card ring-1 ring-hairline shadow-raised-xs inset-shadow-highlight group-active/page:shadow-none group-active/page:inset-shadow-none dark:bg-foreground/12",
} as const;

export function PaginationLink({
  isActive = false,
  size = "icon",
  disabled = false,
  className,
  children,
  ...props
}: PaginationLinkProps) {
  const { variant } = React.useContext(PaginationContext);
  return (
    <Button
      asChild
      variant="ghost"
      size={size}
      disabled={disabled}
      className={cn(
        "group/page relative isolate text-[13px] font-normal text-muted-foreground tabular-nums hover:text-foreground",
        variant === "well" && "hover:bg-card/60",
        isActive &&
          (variant === "well"
            ? "font-medium text-foreground hover:bg-transparent"
            : "font-medium text-primary-foreground hover:bg-transparent hover:text-primary-foreground"),
        // A shade tighter than a standalone button so a row of pages stays compact.
        variant === "well"
          ? size === "icon"
            ? "size-8"
            : "h-8"
          : size === "icon"
            ? "size-9"
            : "h-9",
        className,
      )}
    >
      <a
        data-slot="pagination-link"
        data-active={isActive || undefined}
        aria-current={isActive ? "page" : undefined}
        {...props}
      >
        {isActive && (
          <motion.span
            data-slot="pagination-indicator"
            layoutId="pagination-indicator"
            aria-hidden="true"
            transition={spring}
            className={cn(
              "absolute inset-0 -z-10 rounded-md transition-[background-color,box-shadow] duration-(--motion-fast) motion-reduce:transition-none",
              indicatorClass[variant],
            )}
          />
        )}
        {children}
      </a>
    </Button>
  );
}

function Chevron({ direction }: { direction: "previous" | "next" }) {
  return (
    <svg
      aria-hidden="true"
      viewBox="0 0 16 16"
      fill="none"
      stroke="currentColor"
      strokeWidth="1.5"
      strokeLinecap="round"
      strokeLinejoin="round"
      className={cn(
        "size-4 transition-transform duration-(--motion-fast) ease-enter motion-reduce:transition-none rtl:-scale-x-100",
        direction === "previous"
          ? "group-hover/page:-translate-x-0.5 rtl:group-hover/page:translate-x-0.5"
          : "group-hover/page:translate-x-0.5 rtl:group-hover/page:-translate-x-0.5",
      )}
    >
      <path d={direction === "previous" ? "M10 3.5 5.5 8 10 12.5" : "M6 3.5 10.5 8 6 12.5"} />
    </svg>
  );
}

export function PaginationPrevious({
  className,
  children = "Previous",
  ...props
}: PaginationLinkProps) {
  return (
    <PaginationLink
      aria-label="Go to previous page"
      size="md"
      className={cn("gap-1 px-2.5 text-foreground", className)}
      {...props}
    >
      <Chevron direction="previous" />
      <span className="hidden sm:block">{children}</span>
    </PaginationLink>
  );
}

export function PaginationNext({ className, children = "Next", ...props }: PaginationLinkProps) {
  return (
    <PaginationLink
      aria-label="Go to next page"
      size="md"
      className={cn("gap-1 px-2.5 text-foreground", className)}
      {...props}
    >
      <span className="hidden sm:block">{children}</span>
      <Chevron direction="next" />
    </PaginationLink>
  );
}

export function PaginationEllipsis({
  label = "More pages",
  className,
  ...props
}: React.ComponentProps<"span"> & {
  /** Text read by screen readers in place of the dots. */
  label?: string;
}) {
  const { variant } = React.useContext(PaginationContext);
  return (
    <span
      data-slot="pagination-ellipsis"
      className={cn(
        "flex items-center justify-center text-muted-foreground/70",
        variant === "well" ? "size-8" : "size-9",
        className,
      )}
      {...props}
    >
      <svg aria-hidden="true" viewBox="0 0 16 16" fill="currentColor" className="size-4">
        <circle cx="3.5" cy="8" r="1.1" />
        <circle cx="8" cy="8" r="1.1" />
        <circle cx="12.5" cy="8" r="1.1" />
      </svg>
      <span className="sr-only">{label}</span>
    </span>
  );
}