🎯 Cursorly.js

---

🚀 Features

• 🧩 40+ built-in cursor icons
• 💥 15+ ready-to-use visual effects
• 💫 Emoji particle support
• ⚙️ Easy configuration & real-time customization
• 🪄 Fully extensible — define your own effects!
• 🪶 Lightweight & dependency-free

🎨 Built-in Effects

Effect Name	Description	Type
trail	Rainbow particle trail	default
sparkle	Glitter sparkle effect	default
emoji	Emoji trail (✨)	emoji
firing	Fire-like explosion	firing
circle	Circular light trail	circle
none	Disables particle effect	default
neonGlow	Neon-style glow	default
fireworks	Multi-color burst	default
snowfall	Soft white snow	default
aura	Gradient aura	default
comet	Comet trail	default
emojiHearts	💖 trail	emoji
emojiStars	⭐ trail	emoji
emojiFire	🔥 trail	emoji
emojiSnow	❄️ trail	emoji
emojiMagic	🪄 trail	emoji

🧭 Browser Support

Cursorly.js works in all modern browsers (Chrome, Firefox, Safari, Edge).

⚙️ Installation

Include via CDN:

<script src="https://cdn.jsdelivr.net/gh/iamashruu/cursorly.js@latest/dist/cursorly.min.js"></script>

Or install via NPM:

npm install cursorly.js

🧩 Basic Usage

Initialize the cursor with default options:

const cursor = Cursorly.init();

🎛️ Initialize with Built-in Icon and Effect

Use one of the built-in icons and apply any visual effect:

const cursor = Cursorly.init({
  cursor: 0, // Index of the built-in cursor icon (default: 0)
  effect: { name: "trail", color: "rainbow" } // Apply a built-in effect
});

Or with an emoji-based effect:

const cursor = Cursorly.init({
  cursor: 0, // Built-in icon index
  effect: { name: "emoji", shape: "👻" }
});

🧠 This setup uses the built-in icons included with Cursorly. To use your own image or PNG/SVG icon, see the next section.

🖼️ Add a Custom Cursor Icon

You can add your own custom cursor image (PNG, SVG, etc.) from any URL or local asset path.

const cursor = Cursorly.init();

// Add your own image as a new cursor icon
const cursorIndex = cursor.addIcon('https://img.icons8.com/?size=100&id=52516&format=png&color=000000');

// Activate your custom icon
cursor.setIcon(cursorIndex);

You can register multiple icons and switch between them dynamically:

const custom1 = cursor.addIcon('icon1.png');
const custom2 = cursor.addIcon('icon2.svg');
cursor.setIcon(custom2); // Switch to another custom icon

💡 The method cursor.addIcon() returns the index of your new icon so you can reference it later.

🔁 Switching Between Icons

Change between any previously registered icons (built-in or custom):

cursor.setIcon(1); // Change to built-in icon index 1
cursor.setIcon(cursorIndex); // Switch to your custom icon

✨ Default Effects

Effect options (only name and color are required):

cursor.setEffect({
  name: "sparkle",   // 'trail', 'sparkle', 'emojiSnow', etc.
  color: "#ff4081",  // Hex color or "rainbow"
  density: 10,       // Optional, number of particles per mouse move
  size: [3, 12],     // Optional, min and max particle size
  decay: 0.92,       // Optional, particle shrink rate
});

🧠 Creating Custom Effects

You can define your own effects using the same structure as built-ins:

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

cursor.setEffect(starlightBurst);

You can register unlimited custom effects — Cursorly is fully extensible.

💎 Emoji List

Cursorly includes an emoji selector with 100+ emojis ready to use in effects, including:
✨ 🔥 💖 ❄️ ⭐ 🪄 🤖 🌈 💫 🦋 ⚡ 🍀 🎉 🌸 💎 🎈 🌟 🧠 🕹️ 🌼 🌺 🌻 🧊 🫧 🪐 ☄️

🦋 Custom Emoji Effects

CursorlyJS supports custom emoji effects out of the box.
You can easily create and set them dynamically:

const emojiButterfly = {
  name: "emojiButterfly",
  shape: "🦋",
  color: "white",
  density: 4,
  size: [2, 5],
  decay: 0.85,
  type: "emoji",
};

cursor.setEffect(emojiButterfly);

Alternatively:

cursor.setEffect({
  name: "emoji",
  shape: "👻",
  density: 10,
  size: [3, 12],
  decay: 0.92,
});

Disable or enable effects dynamically:

cursor.disableEffect(); // Turn off particle effects
cursor.enableEffect();  // Turn on particle effects

🧭 Enable / Disable Cursor

Cursorly supports toggling the custom cursor easily:

cursor.disable(); // Hide custom cursor, revert to default
cursor.enable();  // Show custom cursor again

🧑‍💻 Contribution

We welcome contributions from the community!

1. Fork the repo
2. Add your custom icons or effects
3. Submit a PR with a short demo and description

🏷️ Tags

🧡 License

MIT © 2025 [Ashraf]