mouse-animations

A lightweight, framework-agnostic library for cursor and mouse effects. Zero dependencies, under 5 kB gzipped, fully typed. Optional jQuery plugin included.

Live Playground →

---

Effects

Effect	Description
Trail	Fading dot trail that follows the cursor on a canvas overlay
Ripple	Expanding circle at each click position
CustomCursor	Dot + smoothly lagging outer ring replacing the native cursor
Magnetic	Pulls matching elements toward the cursor as it approaches
Particles	Burst of coloured particles on each click
Parallax	Elements shift subtly as the mouse moves across the viewport
Tilt	3D perspective tilt that follows the cursor within each element
Spotlight	Radial gradient glow that follows the cursor inside each element
Invert	Colored circle that inverts content beneath it via mix-blend-mode
Image	Replaces the native cursor with a custom image or inline SVG

---

Installation

npm

npm install mouse-animations

CDN (no build step)

<script type="module">
  import { Trail } from "https://cdn.jsdelivr.net/npm/mouse-animations/+esm";
</script>

---

Usage

Each effect is an independent class. Instantiate to start, call destroy() to clean up.

import { Trail } from "mouse-animations";

const trail = new Trail({ color: "#a78bfa", size: 8 });

trail.disable(); // pause — keeps DOM elements intact
trail.enable(); // resume
trail.destroy(); // stop and remove all DOM elements

All classes share the same interface:

interface MouseAnimationsBase {
  enable(): void; // start or resume the effect
  disable(): void; // pause without removing DOM elements
  destroy(): void; // stop and remove all DOM elements
}

All option types are exported for use in TypeScript projects:

import type {
  TrailOptions, RippleOptions, CustomCursorOptions,
  MagneticOptions, ParticlesOptions, ParallaxOptions,
  TiltOptions, SpotlightOptions, InvertOptions, ImageOptions,
} from "mouse-animations";

---

API

Trail

Renders a fading dot trail that follows the cursor on a canvas overlay.

import { Trail } from "mouse-animations";

const trail = new Trail({
  color: "#ffffff", // dot color
  size: 6, // max dot radius in px
  length: 20, // number of trail points to keep
  decay: 0.05, // alpha subtracted per frame (0–1)
  blur: 0, // CSS blur in px
});

---

Ripple

Creates an expanding ripple circle at each click position.

import { Ripple } from "mouse-animations";

const ripple = new Ripple({
  color: "rgba(255,255,255,0.4)", // fill color
  duration: 600, // animation duration in ms
  maxSize: 100, // max ripple diameter in px
});

---

CustomCursor

Replaces the native cursor with a dot and a smoothly lagging outer ring.

import { CustomCursor } from "mouse-animations";

const cursor = new CustomCursor({
  innerSize: 8, // inner dot size in px
  outerSize: 36, // outer ring size in px
  innerColor: "#ffffff", // inner dot color
  outerColor: "rgba(255,255,255,0.5)", // outer ring color
  smoothness: 0.15, // outer ring lerp factor (0–1); lower = more lag
  hideDefault: true, // hide the native cursor
});

---

Magnetic

Applies a magnetic pull to matching elements as the cursor approaches them. The transform is restored when the cursor leaves.

import { Magnetic } from "mouse-animations";

const magnetic = new Magnetic({
  selector: ".btn", // CSS selector for elements to magnetise (required)
  strength: 0.3, // pull strength multiplier
  radius: 100, // activation radius in px
  ease: 0.15, // lerp ease factor (0–1)
});

---

Particles

Bursts coloured canvas particles from each click position.

import { Particles } from "mouse-animations";

const particles = new Particles({
  count: 20, // particles per click
  colors: ["#ff6b6b", "#ffd93d", "#6bcb77", "#4d96ff"], // colors picked at random
  size: 6, // max particle radius in px
  spread: 8, // initial speed spread
  decay: 0.02, // alpha decay per frame
});

---

Parallax

Shifts matching elements as the mouse moves across the viewport, creating a depth illusion.

import { Parallax } from "mouse-animations";

const parallax = new Parallax({
  selector: ".layer", // CSS selector for elements to shift (required)
  depth: 20, // max translation in px at the viewport edge
  ease: 0.1, // lerp ease factor (0–1)
});

---

Tilt

Applies a 3D perspective tilt to matching elements as the cursor moves over them, with an optional glare highlight.

import { Tilt } from "mouse-animations";

const tilt = new Tilt({
  selector: ".card", // CSS selector for elements to tilt (required)
  maxTilt: 15, // max tilt angle in degrees
  perspective: 800, // CSS perspective distance in px
  ease: 0.1, // lerp ease factor (0–1)
  glare: false, // show a glare highlight overlay
});

---

Spotlight

Renders a radial gradient glow that follows the cursor inside each matched element. Works best on dark cards and panels.

import { Spotlight } from "mouse-animations";

const spotlight = new Spotlight({
  selector: ".card", // CSS selector for elements (required)
  color: "rgba(255,255,255,0.12)", // spotlight glow color
  size: 200, // spotlight radius in px
});

---

Invert

Renders an opaque circle that follows the cursor and inverts the colors of everything beneath it using mix-blend-mode: difference. Works on text, images, and any colored content.

The inversion result depends on the circle color. White (#ffffff, default) produces the classic full inversion. Use a different color if the page background is light — for example #000000 inverts on white backgrounds identically.

import { Invert } from "mouse-animations";

const cursor = new Invert({
  size: 40,          // circle diameter in px
  color: "#ffffff",  // circle color — affects the inversion output. Default: '#ffffff'
  smoothness: 1,     // lerp factor (0–1); 1 = instant snap, lower = lag
  hideDefault: true, // hide the native cursor
});

---

Image

Replaces the native cursor with a custom image URL or inline SVG string.

Note: The name Image shadows the DOM built-in Image constructor (HTMLImageElement) within the same file. If you need both, use an alias:

import { Image as CursorImage } from "mouse-animations";

import { Image } from "mouse-animations";

const cursor = new Image({
  src: "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'>...</svg>",
  width: 32,         // cursor element width in px
  height: 32,        // cursor element height in px
  offsetX: 0,        // horizontal offset from cursor position in px
  offsetY: 0,        // vertical offset from cursor position in px
  smoothness: 1,     // lerp factor (0–1); 1 = instant snap, lower = lag
  hideDefault: true, // hide the native cursor
  overrideAll: false, // inject * { cursor: none !important } — defeats cursor: pointer on buttons/links
  states: {               // alternate images per interaction state (optional)
    hover: "<svg .../>",  // built-in: shown over a, button, input, select, textarea…
    active: "<svg .../>", // built-in: shown while mousedown is held
    ".my-zone": "<svg .../>", // custom: any CSS selector matched via closest()
  },
});

An image URL is also accepted as src:

new Image({ src: "/my-cursor.png", width: 40, height: 40 });

State-based cursors

Use states to show a different cursor image on interactive elements or while the mouse button is held. Any key other than the built-ins is treated as a CSS selector matched via closest().

const cursor = new Image({
  src: starSvg,
  overrideAll: true,
  states: {
    hover: handSvg,         // a, button, input, select, textarea…
    active: clickSvg,       // while mousedown is held
    ".danger-zone": warnSvg, // any CSS selector
  },
});

setSource(state, src)

Swap a cursor image at runtime without recreating the instance:

cursor.setSource("normal", newSvg);
cursor.setSource("hover", newHandSvg);
cursor.setSource(".danger-zone", "/new-warn.png");

---

jQuery plugin

All effects are available as jQuery methods. jQuery >=3.0.0 is an optional peer dependency.

npm install mouse-animations jquery

import "mouse-animations/jquery";

// Global effects — bound to a container element
$("body").trail({ color: "#a78bfa", size: 8 });
$("body").ripple({ duration: 700, maxSize: 120 });
$("body").customCursor({ innerColor: "#a78bfa", smoothness: 0.12 });
$("body").particles({ count: 24 });
$("body").invert({ size: 40, color: "#ffffff" });
$("body").image({ src: "<svg .../>", overrideAll: true, states: { hover: "<svg .../>" } });

// Selector-based effects — one instance covers all matched elements.
// The selector option is optional: if omitted, a unique class is stamped
// onto the matched elements automatically.
$(".btn").magnetic({ strength: 0.4, radius: 120 });
$(".layer").parallax({ depth: 20, ease: 0.1 });
$(".card").tilt({ maxTilt: 15, perspective: 800, glare: true });
$(".card").spotlight({ color: "rgba(255,255,255,0.12)", size: 200 });

// All plugins support enable / disable / destroy
$("body").trail("disable");
$("body").trail("enable");
$("body").trail("destroy");

---

Combining effects

All effects are independent and can run simultaneously:

import { Trail, Ripple, Particles, CustomCursor, Magnetic, Parallax, Tilt, Spotlight, Invert, Image } from "mouse-animations";

const trail     = new Trail({ color: "#a78bfa" });
const ripple    = new Ripple({ color: "rgba(167,139,250,0.35)" });
const particles = new Particles({ count: 24 });
const cursor    = new CustomCursor({ innerColor: "#a78bfa" });
const magnetic  = new Magnetic({ selector: ".magnetic-btn" });
const parallax  = new Parallax({ selector: ".layer" });
const tilt      = new Tilt({ selector: ".card", glare: true });
const spotlight = new Spotlight({ selector: ".card" });
const invert    = new Invert({ size: 40 });
const image     = new Image({ src: starSvg, overrideAll: true });

// Clean up all at once
[trail, ripple, particles, cursor, magnetic, parallax, tilt, spotlight, invert, image].forEach((e) => e.destroy());

---

License

MIT