Add Custom Spotlight Effects to Mouse Movements – gradient-cursor

gradient-cursor is a lightweight JavaScript library that adds a dynamic, customizable gradient effect to your website’s cursor.

Instead of the standard pointer, you see a soft, gradient circle that follows your mouse movements, just like a spotlight.

Features:

• Mouse-tracking radial gradient effect
• RGB color control without alpha channel
• Size configuration via CSS units (vmax/px)
• Animated background transitions
• Basic touch device support

See it in action:

How to use it:

1. Install and import the gradient-cursor library.

# Yarn
$ yarn add gradient-cursor
# NPM
$ npm install gradient-cursor
# PNPM
$ pnpm install gradient-cursor

// CommonJS
const applyGradientCursor = require('gradient-cursor');
// ES Modules
import applyGradientCursor from 'gradient-cursor';

2. Call the applyGradientCursor function.This will apply the default configuration with a dark blue background (#1c2742) and a complementary gradient.

applyGradientCursor();

3. To customize the cursor effect, you can pass a configuration object with these parameters:

• backgroundColor (string, optional): Sets the background-color of the body. Defaults to #1c2742.
• gradientColor (string, optional): The RGB color for the gradient (e.g., "255, 100, 50"). Defaults to '15, 23, 42'.
• gradientSize (string, optional): The size of the gradient circle (use any valid CSS unit). Defaults to '10vmax'.

applyGradientCursor({
  backgroundColor: "#1c2742",
  gradientColor: "15, 23, 42",
  gradientSize: "10vmax"
});

How It Works

The library injects a <style> element into the document head that defines CSS custom properties to track cursor coordinates. The CSS creates a pseudo-element with a radial gradient whose center follows the mouse.

A JavaScript event listener updates CSS variables (--cursorX and --cursorY) in response to mousemove and touchmove events. This approach utilizes the browser’s hardware acceleration and keeps the code minimal. The library supports modern browsers that handle CSS custom properties and animations efficiently.