Interactive Wallpaper

In this tutorial, you'll build a wallpaper that responds to your mouse cursor using the useMousePosition hook.

Prerequisites

Complete the Getting Started tutorial first.

Add Mouse Tracking

Replace the content of src/main.tsx:

src/main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { useMousePosition } from "@fluxlay/react";
 
function Wallpaper() {
  const { x, y } = useMousePosition();
  const px = ((x + 1) / 2) * window.innerWidth;
  const py = (1 - (y + 1) / 2) * window.innerHeight;
 
  return (
    <main
      style={{
        height: "100vh",
        width: "100vw",
        backgroundColor: "#0f0f23",
        overflow: "hidden",
        position: "relative"
      }}
    >
      <div
        style={{
          position: "absolute",
          left: px,
          top: py,
          width: 40,
          height: 40,
          borderRadius: "50%",
          backgroundColor: "#6366f1",
          transform: "translate(-50%, -50%)",
          transition: "left 0.1s ease-out, top 0.1s ease-out",
          boxShadow: "0 0 30px 10px rgba(99, 102, 241, 0.4)"
        }}
      />
    </main>
  );
}
 
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <Wallpaper />
  </StrictMode>
);

Start the dev server and move your mouse — the glowing circle follows your cursor across the screen.

pnpm fluxlay dev

Understanding the Coordinate System

useMousePosition() returns coordinates normalized to the wallpaper window: both x and y range from -1 to 1. The Y axis is mathematical (+1 = top, -1 = bottom), so it's inverted relative to CSS — convert with ((x + 1) / 2) * window.innerWidth and (1 - (y + 1) / 2) * window.innerHeight before using as pixel offsets.

Adding Animation Libraries

For smoother animations, you can use libraries like @react-spring/web:

pnpm add @react-spring/web

src/main.tsx

import { useSpring, animated } from "@react-spring/web";
import { useMousePosition } from "@fluxlay/react";
 
function Wallpaper() {
  const { x, y } = useMousePosition();
  const px = ((x + 1) / 2) * window.innerWidth;
  const py = (1 - (y + 1) / 2) * window.innerHeight;
  const spring = useSpring({ to: { x: px, y: py }, config: { tension: 120, friction: 14 } });
 
  return (
    <main style={{ height: "100vh", width: "100vw", backgroundColor: "#0f0f23" }}>
      <animated.div
        style={{
          position: "absolute",
          left: spring.x,
          top: spring.y,
          width: 40,
          height: 40,
          borderRadius: "50%",
          backgroundColor: "#6366f1",
          transform: "translate(-50%, -50%)"
        }}
      />
    </main>
  );
}

Next Steps

Task-focused guides:

Track Mouse Position — Practical patterns for useMousePosition.
React to Audio — Drive your wallpaper from audio instead of mouse.
Custom Properties — Let users tweak colors and sizes.

Another tutorial:

Shell Wallpaper — Display system info on your wallpaper.

API reference:

useMousePosition