{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "interactive-sprite",
  "title": "Interactive Sprite",
  "description": "Turn a directional sprite sheet into a character that follows the pointer and returns to rest.",
  "files": [
    {
      "path": "src/registry/components/interactive-sprite/interactive-sprite.tsx",
      "content": "\"use client\";\n\nimport type { CSSProperties } from \"react\";\nimport { useEffect, useRef, useState } from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\ntype SpriteFrame = {\n\tcolumn: number;\n\trow: number;\n};\n\ntype Direction =\n\t| \"center\"\n\t| \"east\"\n\t| \"north\"\n\t| \"north-east\"\n\t| \"north-west\"\n\t| \"south\"\n\t| \"south-east\"\n\t| \"south-west\"\n\t| \"west\";\n\nexport type DirectionFrameMap = Record<Direction, SpriteFrame>;\n\nexport type InteractiveSpriteProps = {\n\t/** Accessible description for the character. Use an empty string when decorative. */\n\talt: string;\n\t/** Number of equally sized columns in the sprite sheet. */\n\tcolumns?: number;\n\t/** Distance from the character's center that keeps the resting frame active. */\n\tdeadZone?: number;\n\t/** Maps pointer directions to cells in the sprite sheet. */\n\tframes?: DirectionFrameMap;\n\t/** Time without pointer movement before returning to the center frame. */\n\tidleDelay?: number;\n\t/** Number of equally sized rows in the sprite sheet. */\n\trows?: number;\n\t/** Public URL for the sprite sheet. */\n\tsrc: string;\n\tclassName?: string;\n\tstyle?: CSSProperties;\n};\n\nconst DEFAULT_FRAMES: DirectionFrameMap = {\n\t\"north-west\": { column: 0, row: 0 },\n\tnorth: { column: 1, row: 0 },\n\t\"north-east\": { column: 2, row: 0 },\n\twest: { column: 0, row: 1 },\n\tcenter: { column: 1, row: 1 },\n\teast: { column: 2, row: 1 },\n\t\"south-west\": { column: 0, row: 2 },\n\tsouth: { column: 1, row: 2 },\n\t\"south-east\": { column: 2, row: 2 },\n};\n\nconst OCTANTS: Direction[] = [\n\t\"east\",\n\t\"south-east\",\n\t\"south\",\n\t\"south-west\",\n\t\"west\",\n\t\"north-west\",\n\t\"north\",\n\t\"north-east\",\n];\n\nfunction getDirection(deltaX: number, deltaY: number, deadZone: number) {\n\tif (Math.hypot(deltaX, deltaY) <= deadZone) return \"center\";\n\n\tconst octant =\n\t\t(Math.round(Math.atan2(deltaY, deltaX) / (Math.PI / 4)) + 8) % 8;\n\n\treturn OCTANTS[octant];\n}\n\nfunction getBackgroundPosition(\n\tframe: SpriteFrame,\n\tcolumns: number,\n\trows: number,\n) {\n\tconst x = columns === 1 ? 0 : (frame.column / (columns - 1)) * 100;\n\tconst y = rows === 1 ? 0 : (frame.row / (rows - 1)) * 100;\n\n\treturn `${x}% ${y}%`;\n}\n\nexport function InteractiveSprite({\n\talt,\n\tclassName,\n\tcolumns = 3,\n\tdeadZone = 24,\n\tframes = DEFAULT_FRAMES,\n\tidleDelay = 300,\n\trows = 3,\n\tsrc,\n\tstyle,\n}: InteractiveSpriteProps) {\n\tconst rootRef = useRef<HTMLSpanElement>(null);\n\tconst activeDirectionRef = useRef<Direction>(\"center\");\n\tconst [activeDirection, setActiveDirection] = useState<Direction>(\"center\");\n\n\tuseEffect(() => {\n\t\tconst reducedMotion = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n\t\tlet animationFrame: number | null = null;\n\t\tlet idleTimeout: number | undefined;\n\n\t\tconst resetDirection = () => {\n\t\t\tif (activeDirectionRef.current === \"center\") return;\n\n\t\t\tactiveDirectionRef.current = \"center\";\n\t\t\tsetActiveDirection(\"center\");\n\t\t};\n\n\t\tconst handlePointerMove = (event: PointerEvent) => {\n\t\t\tif (event.pointerType === \"touch\" || reducedMotion.matches) return;\n\n\t\t\twindow.clearTimeout(idleTimeout);\n\t\t\tif (animationFrame !== null) cancelAnimationFrame(animationFrame);\n\n\t\t\tanimationFrame = requestAnimationFrame(() => {\n\t\t\t\tanimationFrame = null;\n\t\t\t\tconst root = rootRef.current;\n\t\t\t\tif (!root || reducedMotion.matches) return;\n\n\t\t\t\tconst bounds = root.getBoundingClientRect();\n\t\t\t\tconst direction = getDirection(\n\t\t\t\t\tevent.clientX - (bounds.left + bounds.width / 2),\n\t\t\t\t\tevent.clientY - (bounds.top + bounds.height / 2),\n\t\t\t\t\tdeadZone,\n\t\t\t\t);\n\n\t\t\t\tif (direction !== activeDirectionRef.current) {\n\t\t\t\t\tactiveDirectionRef.current = direction;\n\t\t\t\t\tsetActiveDirection(direction);\n\t\t\t\t}\n\n\t\t\t\tidleTimeout = window.setTimeout(resetDirection, idleDelay);\n\t\t\t});\n\t\t};\n\n\t\tconst handleMotionPreferenceChange = () => {\n\t\t\tif (reducedMotion.matches) resetDirection();\n\t\t};\n\n\t\twindow.addEventListener(\"pointermove\", handlePointerMove, {\n\t\t\tpassive: true,\n\t\t});\n\t\treducedMotion.addEventListener(\"change\", handleMotionPreferenceChange);\n\n\t\treturn () => {\n\t\t\twindow.removeEventListener(\"pointermove\", handlePointerMove);\n\t\t\treducedMotion.removeEventListener(\"change\", handleMotionPreferenceChange);\n\t\t\twindow.clearTimeout(idleTimeout);\n\t\t\tif (animationFrame !== null) cancelAnimationFrame(animationFrame);\n\t\t};\n\t}, [deadZone, idleDelay]);\n\n\tconst frame = frames[activeDirection];\n\tconst spriteStyle: CSSProperties = {\n\t\tbackgroundImage: `url(\"${src}\")`,\n\t\tbackgroundPosition: getBackgroundPosition(frame, columns, rows),\n\t\tbackgroundRepeat: \"no-repeat\",\n\t\tbackgroundSize: `${columns * 100}% ${rows * 100}%`,\n\t};\n\tconst accessibilityProps = alt\n\t\t? { \"aria-label\": alt, role: \"img\" }\n\t\t: { \"aria-hidden\": true as const };\n\n\treturn (\n\t\t<span\n\t\t\tref={rootRef}\n\t\t\tclassName={cn(\"block overflow-hidden\", className)}\n\t\t\tdata-direction={activeDirection}\n\t\t\tdata-slot=\"interactive-sprite\"\n\t\t\tstyle={style}\n\t\t\t{...accessibilityProps}\n\t\t>\n\t\t\t<span\n\t\t\t\taria-hidden=\"true\"\n\t\t\t\tclassName=\"block size-full\"\n\t\t\t\tstyle={spriteStyle}\n\t\t\t/>\n\t\t</span>\n\t);\n}\n\nexport default InteractiveSprite;\n",
      "type": "registry:component",
      "target": "@components/interactive-sprite.tsx"
    }
  ],
  "meta": {
    "createdAt": "2026-08-06",
    "image": "https://cdn.tentui.com/images/components/interactive-sprite",
    "video": "https://cdn.tentui.com/videos/components/interactive-sprite"
  },
  "docs": "https://tentui.com/components/interactive-sprite",
  "categories": [],
  "type": "registry:component"
}