Fluid Cursor

1"use client";
2 
3import * as React from "react";
4import { createPortal } from "react-dom";
5 
6export type FluidCursorProps = {
7  /** Diameter of the leading dot in pixels. Defaults to `18`. */
8  size?: number;
9  /** Dot color. With `blend` on, `white` reads as a clean invert. Defaults to `white`. */
10  color?: string;
11  /** Invert whatever is underneath via `mix-blend-mode: difference`. Defaults to `true`. */
12  blend?: boolean;
13  /** Render a soft lagging smear behind the dot. Defaults to `true`. */
14  trail?: boolean;
15  /**
16   * Scope the cursor to an element instead of the whole page. The element must
17   * be positioned (e.g. `relative`). Omit for a global cursor.
18   */
19  containerRef?: React.RefObject<HTMLElement | null>;
20  /** Selector for elements that enlarge the cursor on hover. */
21  interactiveSelector?: string;
22  className?: string;
23};
24 
25const FluidCursor = ({
26  size = 18,
27  color = "white",
28  blend = true,
29  trail = true,
30  containerRef,
31  interactiveSelector = "a, button, [role='button'], [data-cursor]",
32  className,
33}: FluidCursorProps) => {
34  const dotRef = React.useRef<HTMLDivElement>(null);
35  const trailRef = React.useRef<HTMLDivElement>(null);
36  const [enabled, setEnabled] = React.useState(false);
37  const [target, setTarget] = React.useState<HTMLElement | null>(null);
38  const motion = React.useRef({
39    x: 0,
40    y: 0,
41    tx: 0,
42    ty: 0,
43    sx: 0,
44    sy: 0,
45    hover: 0,
46    thover: 0,
47    inside: 0,
48    seen: false,
49  });
50 
51  React.useEffect(() => {
52    if (typeof window.matchMedia !== "function") return;
53    const fine = window.matchMedia("(pointer: fine)").matches;
54    const reduce = window.matchMedia(
55      "(prefers-reduced-motion: reduce)",
56    ).matches;
57    setEnabled(fine && !reduce);
58    setTarget(containerRef ? containerRef.current : document.body);
59  }, [containerRef]);
60 
61  React.useEffect(() => {
62    if (!enabled || !target) return;
63    const s = motion.current;
64    const scoped = Boolean(containerRef);
65    const host: HTMLElement | Window = scoped ? target : window;
66 
67    // The follower idles once it catches up to the pointer, so stop the rAF when
68    // everything has settled (or the tab is hidden) and only restart it on real
69    // pointer activity — no forever-spinning loop writing identical transforms.
70    let raf = 0;
71    const SETTLE = 0.01;
72    const settled = () =>
73      Math.abs(s.tx - s.x) < SETTLE &&
74      Math.abs(s.ty - s.y) < SETTLE &&
75      Math.abs(s.tx - s.sx) < SETTLE &&
76      Math.abs(s.ty - s.sy) < SETTLE &&
77// … truncated