JavaScript Cursor Library with Particle Effects – Cursorly.js

Cursorly.js is a JavaScript cursor library that replaces the default mouse pointer with custom icons, particle trails, and emoji effects. It uses Canvas and requestAnimationFrame to draw animated particles from mouse movement.

The library currently includes 40+ cursor icons, 15+ effect names, custom effect settings, and runtime methods for changing icons or effects after initialization.

The effect works best on desktop and laptop interfaces with a fine pointer. For touch-first layouts, initialize Cursorly.js only when the browser reports mouse or trackpad input.

Browse more JavaScript cursor libraries for custom pointers, mouse trails, particle effects, and interactive hover cursors.

Features:

• 40+ built-in cursor icons: Pre-designed cursor shapes ready to use without creating custom assets.
• 15+ cursor effects: Includes trails, sparkles, fireworks, neon glow, snowfall, and more particle animations.
• Emoji particle support: Use any emoji as a particle shape, with built-in effects like hearts, stars, and fire.
• Custom effect creation: Define your own effects with full control over color, density, size, and decay rates.
• Dynamic control: Enable, disable, or switch effects and cursors at runtime without reinitialization.
• Canvas-based rendering: High-performance particle system that doesn’t interfere with page interactions.

How to use it:

1. Download the package and load the main script Cursorly.js in your document.

<script src="/dist/cursorly.min.js"></script>

2. Initialize Cursorly.js with default options. This will create a custom cursor with a rainbow trail effect:

const cursor = Cursorly.init();

3. Customize the cursor icon (0-41):

const cursor = Cursorly.init({
    cursor: 0, // Index of the cursor icon
});

4. Customize the cursor effect. All available effect names:

1. trail
2. sparkle
3. firing
4. circle
5. none
6. neonGlow
7. fireworks
8. snowfall
9. aura
10. comet
11. emoji
12. emojiHearts
13. emojiStars
14. emojiFire
15. emojiSnow
16. emojiMagic

const cursor = Cursorly.init({
  cursor: 20,
  effect: { 
    name: "trail", 
    color: "rainbow",
    density: 10, // Optional: particles per mouse move
    size: [3, 12], // Optional: min and max particle size
    decay: 0.92, // Optional: particle shrink rate
    type: "default", // Optional: define particle rendering type.
  } 
});

5 You can also use a custom emoji. Just set the effect name to "emoji" and provide the character in the shape property.

const cursor = Cursorly.init({
  cursor: 10,
  effect: { 
    name: "emoji", 
    shape:"YOUR EMOJI HERE"
  }
});

6. Switch between cursor icons dynamically:

cursor.setIcon(1);  // Changes to cursor at index 1
cursor.setIcon(5);  // Changes to cursor at index 5

7. Add custom cursors.

const cursorIndex = cursor.addIcon('/path/to/icon/');
cursor.setIcon(cursorIndex);

8. You can also define your own cursor effect that behaves exactly like built-ins.

const starlightBurst = {
  name: "starlightBurst",
  color: ["#ffcc00", "#ffffff", "#ff99ff"],
  density: 8,
  size: [3, 9],
  decay: 0.9,
  type: "default"
};
cursor.setEffect(starlightBurst);

9. More API methods.

• cursor.enableEffect(): Turns on particle effects if they were previously disabled.
• cursor.disableEffect(): Stops particle rendering but keeps the custom cursor visible.
• cursor.enable(): Shows the custom cursor if it was hidden.
• cursor.disable(): Hides the custom cursor and reverts to the browser default.

// Change the active cursor icon by index.
cursor.setIcon(5);
// Register a custom cursor image or SVG and return its index.
const customCursorIndex = cursor.addIcon('/assets/cursor-star.svg');
// Switch to another built-in or custom effect.
cursor.setEffect({
  name: 'sparkle',
  color: '#ffffff',
  density: 8,
  size: [3, 10],
  decay: 0.9,
  type: 'default'
});
// Turn particle rendering on.
cursor.enableEffect();
// Turn particle rendering off while the custom cursor stays visible.
cursor.disableEffect();
// Show the custom cursor.
cursor.enable();
// Hide the custom cursor and return to the browser cursor.
cursor.disable();

FAQs:

Q: How does Cursorly.js impact page performance?
A: It works by drawing particles on a fullscreen canvas element that sits behind your page content. The library is optimized to be lightweight, but a very high particle density on a complex, animation-heavy page could potentially affect performance.

Q: Why aren’t my custom emoji effects working?
A: Make sure you’re setting type: “emoji” and including the shape property with an actual emoji character. The name property can be anything for custom effects, but the type tells Cursorly how to render particles. Also verify your color property is set to “white” or a tint color, not an array.

Q: Does Cursorly work on mobile or touch devices?
A: The library tracks mouse events, so it doesn’t activate on touch-only devices where there’s no cursor. This is actually preferable for mobile UX since custom cursors can interfere with touch interactions. We recommend initializing Cursorly only on devices with pointer capability using matchMedia.

Q: How do I change cursor icons based on what element the user is hovering?
A: The library doesn’t automatically detect hover targets, but you can implement this with event listeners. Add mouseenter handlers to specific elements and call setIcon() when triggered. Remember to store the original icon index if you want to revert when the mouse leaves.

Related Resources:

• 10 Best Custom Cursors Made With jQuery & Vanilla JavaScript
• 90’s Cursor Move Effects In Pure JavaScript
• Interactive WebGL Fluid Motion with Smokey Fluid Cursor
• Create Custom Interactive Mouse Cursors with Cursix and GSAP
• Creative Custom Cursor Library – MagicMouse.js
• oneko.js: Cat Follow Cursor Effect In JavaScript
• Create Smooth Custom Cursor Effects Using Cursor Magic

Changelog:

v1.0.4 (10/20/2025)

• Add any custom images or SVGs as cursors
• Add cursor icons via external image links