Hover Image Reveal

An image follows the cursor across a list.

Aurora Design System2026
Northwind Checkout2025
Field Notes App2025
Sunset Radio2024

Installation

CLI

npx shadcn@latest add https://hantui-theta.vercel.app/r/hover-image-reveal.json

Manual

Install the dependencies
npm install clsx motion tailwind-merge

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 } },
  };
}

Copy the source

components/ui/hover-image-reveal/hover-image-reveal.tsx

"use client";

import { useRef, useState, type ComponentProps, type ElementType, type FocusEvent, type MouseEvent, type PointerEvent, type ReactNode } from "react";
import { AnimatePresence, motion, useMotionValue, useReducedMotion, useSpring, useTransform, useVelocity } from "motion/react";
import { cn } from "@/lib/utils";
import { duration, ease } from "@/lib/motion";

export interface RevealItem {
  /** Stable identity. */
  id: string;
  /** Row title. */
  title: string;
  /** Secondary text on the right, e.g. a year. */
  meta?: string;
  /** Destination. */
  href: string;
  /** Preview that appears beside the cursor, e.g. an image. */
  image: ReactNode;
}

export interface HoverImageRevealProps
  extends Omit<ComponentProps<"div">, "children" | "onAnimationStart" | "onDrag" | "onDragStart" | "onDragEnd"> {
  /** Rows, in order. */
  items: RevealItem[];
  /** Preview width in px. @default 220 */
  imageWidth?: number;
  /** Preview height in px. @default 280 */
  imageHeight?: number;
  /** Link component, e.g. Next.js Link. @default "a" */
  linkComponent?: ElementType;
  /** Called when a row is clicked. */
  onNavigate?: (item: RevealItem, event: MouseEvent<HTMLElement>) => void;
}

const FOLLOW = { stiffness: 260, damping: 26, mass: 0.6 };

export function HoverImageReveal({
  items,
  imageWidth = 220,
  imageHeight = 280,
  linkComponent: Link = "a",
  onNavigate,
  className,
  ...props
}: HoverImageRevealProps) {
  const reduceMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const [active, setActive] = useState<string | null>(null);
  const tx = useMotionValue(0);
  const ty = useMotionValue(0);
  const sx = useSpring(tx, FOLLOW);
  const sy = useSpring(ty, FOLLOW);
  const x = reduceMotion ? tx : sx;
  const y = reduceMotion ? ty : sy;
  // The preview leans into the direction it's travelling.
  const velocity = useVelocity(sx);
  const rotate = useSpring(useTransform(velocity, (v) => (reduceMotion ? 0 : Math.max(-10, Math.min(10, v / 90)))), { stiffness: 220, damping: 22 });

  // Beside the cursor (right of it, flipping left near the edge), vertically centered on it.
  const place = (px: number, py: number, jump: boolean) => {
    const width = rootRef.current?.offsetWidth ?? 0;
    const left = px + 28 + imageWidth > width ? px - 28 - imageWidth : px + 28;
    const top = py - imageHeight / 2;
    if (jump) {
      tx.jump(left);
      ty.jump(top);
      sx.jump(left);
      sy.jump(top);
    } else {
      tx.set(left);
      ty.set(top);
    }
  };

  const onPointerMove = (event: PointerEvent<HTMLDivElement>) => {
    if (event.pointerType !== "mouse") return;
    const rect = event.currentTarget.getBoundingClientRect();
    place(event.clientX - rect.left, event.clientY - rect.top, active === null);
  };

  const current = items.find((item) => item.id === active);

  return (
    <div ref={rootRef} className={cn("relative", className)} onPointerMove={onPointerMove} onPointerLeave={() => setActive(null)} {...props}>
      <ul className="divide-y divide-border border-y border-border">
        {items.map((item) => (
          <li key={item.id}>
            <Link
              href={item.href}
              onClick={(event: MouseEvent<HTMLElement>) => onNavigate?.(item, event)}
              onPointerEnter={(event: PointerEvent<HTMLElement>) => event.pointerType === "mouse" && setActive(item.id)}
              onFocus={(event: FocusEvent<HTMLElement>) => {
                if (!event.currentTarget.matches(":focus-visible")) return;
                // Keyboard focus anchors the preview near the end of the focused row.
                const root = rootRef.current?.getBoundingClientRect();
                const row = event.currentTarget.getBoundingClientRect();
                if (root) place(row.right - root.left - imageWidth - 120, row.top - root.top + row.height / 2, true);
                setActive(item.id);
              }}
              onBlur={() => setActive(null)}
              className={cn(
                "group flex items-baseline justify-between gap-6 py-5 outline-none transition-opacity duration-200 focus-visible:ring-2 focus-visible:ring-ring",
                active !== null && active !== item.id && "opacity-40",
              )}
            >
              <span className="text-2xl font-semibold tracking-tight text-foreground sm:text-3xl">{item.title}</span>
              {item.meta ? <span className="shrink-0 text-sm text-muted-foreground tabular-nums">{item.meta}</span> : null}
            </Link>
          </li>
        ))}
      </ul>

      <motion.div
        aria-hidden="true"
        className="pointer-events-none absolute top-0 left-0 z-10 overflow-hidden rounded-xl shadow-xl"
        style={{ width: imageWidth, height: imageHeight, x, y, rotate }}
        initial={false}
        animate={current ? { opacity: 1, scale: 1 } : { opacity: 0, scale: reduceMotion ? 1 : 0.85 }}
        transition={{ duration: duration.base, ease: ease.out }}
      >
        <AnimatePresence initial={false}>
          {current ? (
            // Each new preview wipes up from the bottom over the previous one.
            <motion.div
              key={current.id}
              className="absolute inset-0"
              initial={reduceMotion ? { opacity: 0 } : { clipPath: "inset(100% 0% 0% 0%)", scale: 1.12 }}
              animate={{ clipPath: "inset(0% 0% 0% 0%)", scale: 1, opacity: 1 }}
              exit={{ opacity: 0, transition: { duration: duration.quick, delay: 0.2 } }}
              transition={{ duration: duration.slow, ease: ease.out }}
            >
              {current.image}
            </motion.div>
          ) : null}
        </AnimatePresence>
      </motion.div>
    </div>
  );
}

Usage

import Link from "next/link";
import { HoverImageReveal } from "@/components/ui/hover-image-reveal/hover-image-reveal";

export function Work() {
  return (
    <HoverImageReveal
      linkComponent={Link}
      items={[
        { id: "aurora", title: "Aurora Design System", meta: "2026", href: "/work/aurora", image: <img src="/aurora.jpg" alt="" /> },
      ]}
    />
  );
}

API reference

Prop	Type	Default	Description
`items*`	`RevealItem[]`	–	Rows, in order.
`imageWidth`	`number`	`220`	Preview width in px.
`imageHeight`	`number`	`280`	Preview height in px.
`linkComponent`	`ElementType`	`"a"`	Link component, e.g. Next.js Link.
`onNavigate`	`(item: RevealItem, event: MouseEvent<HTMLElement>) => void`	–	Called when a row is clicked.

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

The preview springs after the cursor, leans in the direction it's travelling, and flips to the left near the right edge.
Each new image wipes up from the bottom with clip-path while the previous one fades out underneath.
Touch devices don't get a floating preview; the list works as normal links.

Accessibility

A plain list of links; the floating preview is decorative and aria-hidden.
Keyboard focus shows the preview too, anchored beside the focused row.
With reduced motion enabled, the preview follows without lag or tilt and swaps with a fade.

Installation#

CLI

Manual

Install the dependencies

Add the shared helpers

Copy the source

Usage#

API reference#

Accessibility#

Installation

Usage

API reference

Accessibility