{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"mask-reveal-on-hover","type":"registry:component","title":"Mask Reveal on Hover","description":"A round window that follows the cursor and shows different content underneath.","author":"DiMaac (HankTheTank) <https://dimaac.com>","dependencies":["gsap","@gsap/react"],"files":[{"path":"registry/dimaac/mask-reveal-on-hover/mask-reveal-on-hover.tsx","type":"registry:component","target":"components/dimaac/mask-reveal-on-hover.tsx","content":"\"use client\";\n\nimport { useRef, type CSSProperties, type ReactNode } from \"react\";\nimport { gsap } from \"gsap\";\nimport { useGSAP } from \"@gsap/react\";\n\n// A round window that follows the cursor. Through it you see a second layer (a colour and\n// different content) that sits exactly on top of the first one. The window is a CSS mask:\n// a radial gradient whose centre and radius are three CSS variables, and GSAP animates them.\n// The window is small while you move over empty space and grows when you are over the content.\n// On touch screens it follows your finger. With the keyboard, Tab to it and use the arrow keys.\n\nexport type MaskRevealOnHoverProps = {\n  /** What people see normally. */\n  content: ReactNode;\n  /** What shows inside the round window. It is laid on top of `content`, so give both the same width and they line up. */\n  reveal: ReactNode;\n  /** Radius of the window while it is only moving around, in pixels. */\n  size?: number;\n  /** Radius of the window while it is over the content, in pixels. */\n  hoverSize?: number;\n  /** How soft the edge of the window is, in pixels. 0 is a clean circle. */\n  feather?: number;\n  /** How long the window takes to catch up with the cursor, in seconds. */\n  duration?: number;\n  /** The GSAP ease of that catch-up, e.g. \"power3.out\" or \"back.out(1.7)\". */\n  ease?: string;\n  /** Where the window grows to its big size: only over the content, or anywhere in the box. */\n  growOn?: \"content\" | \"stage\";\n  /** The colour of the layer inside the window. Any CSS colour or gradient. */\n  maskBackground?: string;\n  /** Hide the normal cursor inside the box, so the window is the cursor. */\n  hideCursor?: boolean;\n  /** Stop a finger from scrolling the page while it drags the window. Turn it off if the box sits in a long page. */\n  lockTouchScroll?: boolean;\n  /** Describes the box for screen readers and keyboard users. */\n  label?: string;\n  /** Extra classes for the outer box. Give it a size (it fills it). */\n  className?: string;\n};\n\n// The window never needs to be sharper than one pixel, which also keeps the edge smooth\nconst HAIRLINE = 1;\nconst KEY_STEP = 56;\n\nconst hiddenStyle: CSSProperties = {\n  position: \"absolute\",\n  width: 1,\n  height: 1,\n  overflow: \"hidden\",\n  clip: \"rect(0 0 0 0)\",\n  whiteSpace: \"nowrap\",\n};\n\nexport function MaskRevealOnHover({\n  content,\n  reveal,\n  size = 20,\n  hoverSize = 100,\n  feather = 0,\n  duration = 0.6,\n  ease = \"back.out(1.7)\",\n  growOn = \"content\",\n  maskBackground = \"#DDFC3E\",\n  hideCursor = true,\n  lockTouchScroll = true,\n  label = \"Move the cursor over the text to reveal what is underneath. With the keyboard, use the arrow keys.\",\n  className = \"\",\n}: MaskRevealOnHoverProps) {\n  const boxRef = useRef<HTMLDivElement>(null);\n  const contentRef = useRef<HTMLDivElement>(null);\n  const maskRef = useRef<HTMLDivElement>(null);\n  // What the window is doing, kept outside the effect so a prop change (the playground) doesn't make it vanish or jump.\n  // x, y and size are what is painted right now; goalX and goalY are where it is heading.\n  const lens = useRef({ x: 0, y: 0, size: 0, goalX: 0, goalY: 0, present: false, overContent: false, keyboard: false });\n\n  useGSAP(\n    (_context, contextSafe) => {\n      const box = boxRef.current;\n      const inner = contentRef.current;\n      const mask = maskRef.current;\n      if (!box || !inner || !mask || !contextSafe) return;\n\n      const state = lens.current;\n      const reducedMotion = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n\n      // Write the three numbers into the CSS variables the mask reads\n      const paint = () => {\n        mask.style.setProperty(\"--mask-x\", `${state.x}px`);\n        mask.style.setProperty(\"--mask-y\", `${state.y}px`);\n        mask.style.setProperty(\"--mask-size\", `${Math.max(0, state.size)}px`);\n      };\n\n      // quickTo is made for this: cheap to call on every pointer move, always eased toward the newest value.\n      // To make the window jump, the old ones are dropped and new ones are made.\n      let moveX = gsap.quickTo(state, \"x\", { duration, ease, onUpdate: paint });\n      let moveY = gsap.quickTo(state, \"y\", { duration, ease, onUpdate: paint });\n      const makeFollowers = () => {\n        gsap.killTweensOf(state, \"x,y\");\n        moveX = gsap.quickTo(state, \"x\", { duration, ease, onUpdate: paint });\n        moveY = gsap.quickTo(state, \"y\", { duration, ease, onUpdate: paint });\n      };\n\n      let sizeTween: gsap.core.Tween | null = null;\n\n      const wantedSize = () => {\n        if (!state.present) return 0;\n        return growOn === \"stage\" || state.overContent || state.keyboard ? hoverSize : size;\n      };\n\n      const updateSize = () => {\n        const wanted = wantedSize();\n        sizeTween?.kill();\n        if (reducedMotion.matches) {\n          state.size = wanted;\n          paint();\n          return;\n        }\n        const growing = wanted > state.size;\n        sizeTween = gsap.to(state, { size: wanted, duration: growing ? 0.4 : 0.3, ease: growing ? \"power2.out\" : \"power2.in\", onUpdate: paint });\n      };\n\n      // The first touch of a visit puts the window right under the finger, instead of sweeping in from where it was\n      const jumpTo = (x: number, y: number) => {\n        state.x = state.goalX = x;\n        state.y = state.goalY = y;\n        makeFollowers();\n        paint();\n      };\n\n      const goTo = (x: number, y: number) => {\n        if (reducedMotion.matches) {\n          jumpTo(x, y);\n          return;\n        }\n        state.goalX = x;\n        state.goalY = y;\n        moveX(x);\n        moveY(y);\n      };\n\n      const follow = (event: PointerEvent) => {\n        const rect = box.getBoundingClientRect();\n        const x = event.clientX - rect.left;\n        const y = event.clientY - rect.top;\n        const wasPresent = state.present;\n        const wasOver = state.overContent;\n        state.keyboard = false;\n        state.present = true;\n        // A finger keeps the element it first touched as the event target for the whole drag, so for touch and pen\n        // we ask what is under the finger right now. (The mask layer ignores pointers, so it never gets in the way.)\n        const under = event.pointerType === \"mouse\" ? event.target : document.elementFromPoint(event.clientX, event.clientY);\n        state.overContent = under instanceof Node && inner.contains(under);\n        if (!wasPresent) jumpTo(x, y);\n        else goTo(x, y);\n        if (!wasPresent || wasOver !== state.overContent) updateSize();\n      };\n\n      const leave = () => {\n        state.present = false;\n        state.overContent = false;\n        state.keyboard = false;\n        updateSize();\n      };\n\n      const onPointerMove = contextSafe((event: PointerEvent) => {\n        if (!event.isPrimary) return;\n        follow(event);\n      });\n      const onPointerDown = contextSafe((event: PointerEvent) => {\n        if (!event.isPrimary) return;\n        follow(event);\n      });\n      const onPointerLeave = contextSafe((event: PointerEvent) => {\n        if (!event.isPrimary) return;\n        leave();\n      });\n      // A finger that lifts is gone; a mouse button that lifts is still over the box\n      const onPointerUp = contextSafe((event: PointerEvent) => {\n        if (event.isPrimary && event.pointerType !== \"mouse\") leave();\n      });\n\n      // Keyboard: Tab puts the big window in the middle, the arrow keys walk it around\n      const onFocus = contextSafe(() => {\n        if (!box.matches(\":focus-visible\")) return;\n        state.keyboard = true;\n        state.present = true;\n        state.overContent = true;\n        jumpTo(box.clientWidth / 2, box.clientHeight / 2);\n        updateSize();\n      });\n      const onBlur = contextSafe(() => {\n        if (state.keyboard) leave();\n      });\n      const onKeyDown = contextSafe((event: KeyboardEvent) => {\n        if (!state.keyboard) return;\n        const step = { ArrowLeft: [-KEY_STEP, 0], ArrowRight: [KEY_STEP, 0], ArrowUp: [0, -KEY_STEP], ArrowDown: [0, KEY_STEP] }[event.key];\n        if (!step) return;\n        event.preventDefault();\n        // Step from where the window is heading, so quick key presses add up\n        goTo(gsap.utils.clamp(0, box.clientWidth, state.goalX + step[0]!), gsap.utils.clamp(0, box.clientHeight, state.goalY + step[1]!));\n      });\n\n      box.addEventListener(\"pointermove\", onPointerMove);\n      box.addEventListener(\"pointerdown\", onPointerDown);\n      box.addEventListener(\"pointerleave\", onPointerLeave);\n      box.addEventListener(\"pointerup\", onPointerUp);\n      box.addEventListener(\"pointercancel\", onPointerUp);\n      box.addEventListener(\"focus\", onFocus);\n      box.addEventListener(\"blur\", onBlur);\n      box.addEventListener(\"keydown\", onKeyDown);\n\n      // A prop change rebuilds this effect: carry on from where the window already is, at the new size\n      state.size = wantedSize();\n      paint();\n      if (state.present && !reducedMotion.matches) {\n        moveX(state.goalX);\n        moveY(state.goalY);\n      }\n\n      return () => {\n        box.removeEventListener(\"pointermove\", onPointerMove);\n        box.removeEventListener(\"pointerdown\", onPointerDown);\n        box.removeEventListener(\"pointerleave\", onPointerLeave);\n        box.removeEventListener(\"pointerup\", onPointerUp);\n        box.removeEventListener(\"pointercancel\", onPointerUp);\n        box.removeEventListener(\"focus\", onFocus);\n        box.removeEventListener(\"blur\", onBlur);\n        box.removeEventListener(\"keydown\", onKeyDown);\n        sizeTween?.kill();\n        gsap.killTweensOf(state);\n      };\n    },\n    { scope: boxRef, dependencies: [size, hoverSize, feather, duration, ease, growOn], revertOnUpdate: true },\n  );\n\n  // A circle of `--mask-size` around (`--mask-x`, `--mask-y`): solid inside, clear outside\n  // A soft edge can be at most 60% of the radius, so the small idle dot stays solid in the middle\n  const edge = `max(${HAIRLINE}px, min(${feather}px, var(--mask-size, 0px) * 0.6))`;\n  const circle = `radial-gradient(circle at var(--mask-x, -100px) var(--mask-y, -100px), #000 calc(var(--mask-size, 0px) - ${edge}), transparent var(--mask-size, 0px))`;\n\n  return (\n    <div\n      ref={boxRef}\n      role=\"group\"\n      aria-label={label}\n      tabIndex={0}\n      className={`relative isolate grid h-full w-full place-items-center overflow-hidden outline-offset-[-3px] ${className}`}\n      style={{ cursor: hideCursor ? \"none\" : undefined, touchAction: lockTouchScroll ? \"none\" : \"pan-y\" }}\n    >\n      <div ref={contentRef} className=\"relative z-0 max-w-full\">\n        {content}\n      </div>\n\n      {/* The same words as the layer above, but for screen readers only, so nothing is said twice */}\n      <div style={hiddenStyle}>{reveal}</div>\n\n      <div\n        ref={maskRef}\n        aria-hidden=\"true\"\n        className=\"pointer-events-none absolute inset-0 z-10 grid place-items-center\"\n        style={{ background: maskBackground, WebkitMaskImage: circle, maskImage: circle, willChange: \"mask-image\" }}\n      >\n        {reveal}\n      </div>\n    </div>\n  );\n}\n"}],"categories":["cursor","gsap","mask","text","hover"],"docs":"import { MaskRevealOnHover } from \"@/components/dimaac/mask-reveal-on-hover\". Give its parent a size: it fills it. Docs, playground and props: https://ui.dimaac.com/components/mask-reveal-on-hover","meta":{"tier":"free","preview":"https://ui.dimaac.com/components/mask-reveal-on-hover","credits":[]}}