Custom Cursor Library with Animated Particle Effects – Cursorly.js

Cursorly.js is a JavaScript custom cursor library that allows you to create 40+ various cursors with animated trails, emojis, and particle effects.

It works in all modern browsers that support the Canvas API. We’ve tested it successfully in Chrome, Firefox, Safari, and Edge.

The library uses requestAnimationFrame for smooth particle animations and handles mouse events efficiently enough for 60fps rendering on most hardware.

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:

• trail
• sparkle
• firing
• circle
• none
• neonGlow
• fireworks
• snowfall
• aura
• comet
• emoji
• emojiHearts
• emojiStars
• emojiFire
• emojiSnow
• 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. You can also define your own cursor effect that behave 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);

8. 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.

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

The post Custom Cursor Library with Animated Particle Effects – Cursorly.js appeared first on CSS Script.