Skip to content
hantui

Navigationv0.1.0

Animated Pagination

A sliding indicator with rolling page numbers.

Installation

CLI

npx shadcn@latest add https://hantui-theta.vercel.app/r/animated-pagination.json

Manual

  1. Install the dependencies

    npm install clsx lucide-react motion tailwind-merge

  2. Add the shared helpers

    Components use cn() from lib/utils.ts and the motion tokens below. See Installation if you have not set them up yet.

    lib/motion.ts
    import type { Transition, Variants } from "motion/react";

/** Durations in seconds. */
export const duration = {
  instant: 0.1,
  quick: 0.18,
  base: 0.28,
  slow: 0.45,
} as const;

/** Cubic-bezier curves. */
export const ease = {
  /** Entering, UI response. */
  out: [0.22, 1, 0.36, 1],
  /** Moving on screen. */
  inOut: [0.65, 0, 0.35, 1],
  /** Sheets and the mobile menu. */
  drawer: [0.32, 0.72, 0, 1],
} as const;

/** Everyday UI: presses, icon swaps, popovers and modals. Exits run at `exitFactor` of the enter. */
export const ui = {
  press: { scale: 0.96, duration: 0.12 },
  icon: { type: "spring", duration: 0.3, bounce: 0 },
  popover: { duration: 0.18, ease: ease.out },
  modal: { duration: 0.24, ease: ease.out },
  exitFactor: 0.6,
} as const;

/** Once-per-visit motion on the landing page: hero letters, the reel and the afterimage. */
export const kinetic = {
  heroLetter: { duration: 0.6, ease: ease.out },
  /** Delay per letter, eased so the wave slows toward the end. */
  heroStep: 0.035,
  reelSwap: { type: "spring", duration: 0.5, bounce: 0.1 },
  /** Two afterimages: lag in seconds and opacity of each. */
  ghost: { lag: [0.04, 0.09], opacity: [0.14, 0.06] },
} as const;

/** Spring presets. */
export const spring = {
  snappy: { type: "spring", stiffness: 500, damping: 30 },
  smooth: { type: "spring", stiffness: 260, damping: 26 },
  bouncy: { type: "spring", stiffness: 300, damping: 15 },
} as const satisfies Record<string, Transition>;

/** Stagger between siblings, in seconds (0.03–0.06). */
export const stagger = {
  tight: 0.03,
  base: 0.045,
  loose: 0.06,
} as const;

/** Blur + fade + y-offset. Falls back to a plain fade under reduced motion. */
export function enterVariants(reduceMotion?: boolean | null, y = 8): Variants {
  if (reduceMotion) {
    return {
      hidden: { opacity: 0 },
      visible: { opacity: 1, transition: { duration: duration.base } },
      exit: { opacity: 0, transition: { duration: duration.quick } },
    };
  }
  return {
    hidden: { opacity: 0, y, filter: "blur(4px)" },
    visible: {
      opacity: 1,
      y: 0,
      filter: "blur(0px)",
      transition: { duration: duration.base, ease: ease.out },
    },
    exit: {
      opacity: 0,
      y: -y / 2,
      filter: "blur(4px)",
      transition: { duration: duration.quick, ease: ease.out },
    },
  };
}

/** Scale 0.96 → 1 for popovers, menus and dialogs. */
export function overlayVariants(reduceMotion?: boolean | null): Variants {
  if (reduceMotion) {
    return {
      hidden: { opacity: 0 },
      visible: { opacity: 1, transition: { duration: duration.quick } },
      exit: { opacity: 0, transition: { duration: duration.instant } },
    };
  }
  return {
    hidden: { opacity: 0, scale: 0.96, filter: "blur(2px)" },
    visible: {
      opacity: 1,
      scale: 1,
      filter: "blur(0px)",
      transition: { duration: duration.quick, ease: ease.out },
    },
    exit: {
      opacity: 0,
      scale: 0.96,
      filter: "blur(2px)",
      transition: { duration: duration.instant + 0.02, ease: ease.out },
    },
  };
}

/** Parent variants that stagger their children in. */
export function staggerVariants(gap: number = stagger.base, delayChildren = 0): Variants {
  return {
    hidden: {},
    visible: { transition: { staggerChildren: gap, delayChildren } },
    exit: { transition: { staggerChildren: gap / 2, staggerDirection: -1 } },
  };
}

  3. Copy the source

    components/ui/animated-pagination/animated-pagination.tsx
    "use client";

import { useId, useState, type ComponentProps } from "react";
import { AnimatePresence, LayoutGroup, motion, useReducedMotion, type Variants } from "motion/react";
import { ChevronLeft, ChevronRight } from "lucide-react";
import { cn } from "@/lib/utils";
import { duration, ease, spring } from "@/lib/motion";

export interface AnimatedPaginationProps
  extends Omit<ComponentProps<"nav">, "children" | "onAnimationStart" | "onDrag" | "onDragStart" | "onDragEnd"> {
  /** Number of pages. */
  totalPages: number;
  /** Controlled current page (1-based). */
  page?: number;
  /** Initial page when uncontrolled. @default 1 */
  defaultPage?: number;
  /** Called with the new page. */
  onPageChange?: (page: number) => void;
  /** Pages shown on each side of the current one. @default 1 */
  siblingCount?: number;
}

type Slot = number | "gap";

/** A fixed number of slots, so a shifting window rolls numbers in place instead of reflowing. */
function slotsFor(page: number, total: number, siblings: number): Slot[] {
  const size = siblings * 2 + 5; // first, gap, siblings…, current, …siblings, gap, last
  if (total <= size) return Array.from({ length: total }, (_, i) => i + 1);
  const left = Math.max(page - siblings, 1);
  const right = Math.min(page + siblings, total);
  const showLeftGap = left > 3;
  const showRightGap = right < total - 2;
  if (!showLeftGap) return [...Array.from({ length: size - 2 }, (_, i) => i + 1), "gap", total];
  if (!showRightGap) return [1, "gap", ...Array.from({ length: size - 2 }, (_, i) => total - (size - 3) + i)];
  return [1, "gap", ...Array.from({ length: right - left + 1 }, (_, i) => left + i), "gap", total];
}

export function AnimatedPagination({
  totalPages,
  page,
  defaultPage = 1,
  onPageChange,
  siblingCount = 1,
  className,
  "aria-label": ariaLabel = "Pagination",
  ...props
}: AnimatedPaginationProps) {
  const [internal, setInternal] = useState(defaultPage);
  const current = Math.min(Math.max(page ?? internal, 1), Math.max(totalPages, 1));
  const reduceMotion = useReducedMotion();
  const groupId = useId();

  // Numbers roll up when moving forward and down when moving back.
  const [previous, setPrevious] = useState(current);
  const [direction, setDirection] = useState(1);
  if (previous !== current) {
    setDirection(current > previous ? 1 : -1);
    setPrevious(current);
  }

  const go = (next: number) => {
    const clamped = Math.min(Math.max(next, 1), totalPages);
    if (clamped === current) return;
    if (page === undefined) setInternal(clamped);
    onPageChange?.(clamped);
  };

  const slots = slotsFor(current, totalPages, siblingCount);
  const roll: Variants = reduceMotion
    ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 } }
    : {
        initial: (dir: number) => ({ y: dir > 0 ? "70%" : "-70%", opacity: 0, filter: "blur(2px)" }),
        animate: { y: "0%", opacity: 1, filter: "blur(0px)" },
        exit: (dir: number) => ({ y: dir > 0 ? "-70%" : "70%", opacity: 0, filter: "blur(2px)" }),
      };

  const arrow =
    "inline-flex h-9 w-[1.875rem] cursor-pointer items-center justify-center rounded-md text-muted-foreground outline-none transition-colors hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40 sm:w-9 [&_svg]:size-4";

  return (
    <nav aria-label={ariaLabel} className={className} {...props}>
      <LayoutGroup id={groupId}>
        {/* Slightly narrower slots below sm keep a 7-slot window inside a 320px screen. */}
        <ul className="flex items-center gap-0.5 sm:gap-1">
          <li>
            <button type="button" className={arrow} onClick={() => go(current - 1)} disabled={current <= 1} aria-label="Previous page">
              <ChevronLeft aria-hidden="true" />
            </button>
          </li>
          {slots.map((slot, index) => {
            if (slot === "gap") {
              return (
                <li key={`slot-${index}`} aria-hidden="true" className="flex h-9 w-[1.875rem] items-center justify-center text-sm text-muted-foreground sm:w-9">
                  …
                </li>
              );
            }
            const active = slot === current;
            return (
              <li key={`slot-${index}`}>
                <button
                  type="button"
                  onClick={() => go(slot)}
                  aria-label={`Page ${slot}`}
                  aria-current={active ? "page" : undefined}
                  className={cn(
                    "relative after:absolute after:inset-x-0 after:-inset-y-0.5 inline-flex h-9 min-w-[1.875rem] cursor-pointer items-center justify-center rounded-md px-1.5 text-sm font-medium tabular-nums outline-none sm:min-w-9 sm:px-2",
                    "transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-ring",
                    active ? "text-background" : "text-muted-foreground hover:bg-accent hover:text-foreground",
                  )}
                >
                  {active ? (
                    <motion.span
                      layoutId="active-page"
                      aria-hidden="true"
                      transition={reduceMotion ? { duration: 0 } : spring.snappy}
                      className="absolute inset-0 rounded-md bg-foreground shadow-sm"
                    />
                  ) : null}
                  <span aria-hidden="true" className="relative inline-flex h-5 items-center overflow-hidden">
                    <AnimatePresence mode="popLayout" initial={false} custom={direction}>
                      <motion.span
                        key={slot}
                        custom={direction}
                        variants={roll}
                        initial="initial"
                        animate="animate"
                        exit="exit"
                        transition={{ duration: duration.base, ease: ease.out }}
                        className="inline-block"
                      >
                        {slot}
                      </motion.span>
                    </AnimatePresence>
                  </span>
                </button>
              </li>
            );
          })}
          <li>
            <button type="button" className={arrow} onClick={() => go(current + 1)} disabled={current >= totalPages} aria-label="Next page">
              <ChevronRight aria-hidden="true" />
            </button>
          </li>
        </ul>
      </LayoutGroup>
    </nav>
  );
}

Usage

import { AnimatedPagination } from "@/components/ui/animated-pagination/animated-pagination";

export function Results({ total }: { total: number }) {
  const [page, setPage] = useState(1);
  return <AnimatedPagination totalPages={total} page={page} onPageChange={setPage} />;
}

API reference

PropTypeDefaultDescription
totalPages*number–Number of pages.
pagenumber–Controlled current page (1-based).
defaultPagenumber1Initial page when uncontrolled.
onPageChange(page: number) => void–Called with the new page.
siblingCountnumber1Pages shown on each side of the current one.

Also accepts every native <nav> attribute, including ref and className.

  • The window always has the same number of slots (siblingCount × 2 + 5), so moving through pages rolls numbers in place instead of reflowing the row.
  • Use siblingCount={0} for tight spaces, such as below a table on mobile.

Accessibility

  • A labelled <nav> list; each page is a button labelled "Page 3", and the current one has aria-current="page".
  • Previous and Next are labelled and disabled at the ends.
  • Gaps (…) are aria-hidden, since they aren't interactive.
  • With reduced motion enabled, numbers cross-fade instead of rolling and the indicator jumps.