Beautiful, customizable cursor effects for React and vanilla JavaScript. Add magical fairy dust particles that follow your cursor with minimal setup.
Beautiful, customizable cursor particle effects for React and vanilla JavaScript. Create magical experiences with effects like bubbles, snow, sparkles, and more!
🎮 Live Demo | 📖 Documentation | ⭐ GitHub
✨ Experience magical cursor effects with 6 stunning built-in animations ✨
# npm
npm install cursor-fx
# yarn
yarn add cursor-fx
# pnpm
pnpm add cursor-fx
import { CursorFX } from 'cursor-fx/react';
function App() {
return (
<>
<CursorFX effect="bubble" />
<YourContent />
</>
);
}
import { initCursorFX } from 'cursor-fx/vanilla';
const fx = initCursorFX({
effect: 'snow',
particleCount: 2
});
// Later, to clean up:
fx.destroy();
Use directly in your HTML without any build tools:
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<h1>Hello World</h1>
<!-- Load from CDN -->
<script src="https://unpkg.com/cursor-fx@latest/dist/cdn/cursor-fx.min.js"></script>
<script>
// Use the global CursorFX object
const fx = CursorFX.initCursorFX({
effect: 'bubble'
});
</script>
</body>
</html>
CDN Options:
https://unpkg.com/cursor-fx@latest/dist/cdn/cursor-fx.min.jshttps://cdn.jsdelivr.net/npm/cursor-fx@latest/dist/cdn/cursor-fx.min.jsAvailable via global CursorFX object:
CursorFX.initCursorFX(options) - Initialize effectsCursorFX.ImageLoader - Preload images (optional)Floating soap bubbles that drift upward with a smooth pop-up animation.
<CursorFX effect="bubble" />
Features:
Delicate snowflakes that fall and drift with wind.
<CursorFX effect="snow" />
Features:
Golden magical particles that float upward.
<CursorFX effect="fairyDust" />
Features:
Quick, colorful sparkles that burst and fade.
<CursorFX effect="sparkle" />
Features:
Celebratory confetti that falls from cursor.
<CursorFX effect="confetti" />
Features:
Phosphor green glow like old computer terminals.
<CursorFX effect="retroCRT" />
Features:
All effects support extensive customization:
<CursorFX
effect="bubble"
particleCount={3}
colors={['#FF6B6B', '#4ECDC4', '#FFE66D']}
/>
| Option | Type | Description | Default |
|---|---|---|---|
effect | CursorEffectType | Effect name | Required |
particleCount | number | Particles per spawn | Effect-specific |
colors | string[] | Particle colors | Effect-specific |
particleSize | number | Base particle size | Effect-specific |
enabled | boolean | Enable/disable | true (React) |
interface EffectOptions {
colors?: string[]; // Particle colors
particleCount?: number; // Particles per spawn
particleSize?: number; // Base size
gravity?: number; // Vertical acceleration
maxLife?: number; // Lifetime in frames
velocity?: number; // Movement speed
throttle?: number; // Ms between spawns
minMoveDistance?: number; // Min cursor movement
}
See EFFECT_DEFAULTS.md for complete default values.
Quick Reference:
// All effects work with no options:
<CursorFX effect="bubble" /> // Uses all defaults
<CursorFX effect="snow" /> // Uses all defaults
// Or customize only what you need:
<CursorFX effect="bubble" particleCount={5} />
<CursorFX effect="snow" colors={['#FFFFFF']} />
import { CursorFX } from 'cursor-fx/react';
<CursorFX
enabled={true}
effect="bubble"
particleCount={2}
colors={['#FFD700', '#FF69B4']}
/>
Props:
enabled?: boolean - Enable/disable effecteffect: CursorEffectType - Effect nameEffectOptions are also valid propsimport { initCursorFX } from 'cursor-fx/vanilla';
const fx = initCursorFX({
effect: 'snow',
particleCount: 3,
colors: ['#FFFFFF', '#E0FFFF']
});
// Clean up when done
fx.destroy();
For advanced use cases, use the core engine directly:
import {
CursorFXEngine,
createBubbleEffect,
ImageLoader
} from 'cursor-fx';
// Preload images (optional)
await ImageLoader.loadBubbles('/bubbles');
await ImageLoader.loadSnowflakes('/snowflakes');
// Create engine and effect
const engine = new CursorFXEngine();
const effect = createBubbleEffect({
particleCount: 2,
colors: ['#ADD8E6']
});
engine.start(effect);
// Later
engine.stop();
engine.destroy();
The Bubble and Snow effects support PNG images for photorealistic quality. If images aren't loaded, they automatically fall back to canvas-drawn shapes.
1. Copy the images to your public directory:
The package includes high-quality PNG assets. Copy them from node_modules/cursor-fx/dist/bubbles/ and node_modules/cursor-fx/dist/snowflakes/ to your project's public directory:
# Example structure
public/
bubbles/
soap_bubbles_1.png
soap_bubble_2.png
soap_bubble_3.png
snowflakes/
snow_flake_1.png
snow_flake_2.png
2. Preload images before using the effects:
import { useEffect } from 'react';
import { CursorFX, ImageLoader } from 'cursor-fx/react';
function App() {
// Preload images on mount
useEffect(() => {
ImageLoader.loadBubbles('/bubbles')
.then(() => console.log('✓ Bubble images loaded'))
.catch(err => console.warn('Failed to load bubbles:', err));
ImageLoader.loadSnowflakes('/snowflakes')
.then(() => console.log('✓ Snowflake images loaded'))
.catch(err => console.warn('Failed to load snowflakes:', err));
}, []);
return <CursorFX effect="bubble" />;
}
import { initCursorFX, ImageLoader } from 'cursor-fx/vanilla';
// Preload images first
Promise.all([
ImageLoader.loadBubbles('/bubbles'),
ImageLoader.loadSnowflakes('/snowflakes')
])
.then(() => {
console.log('✓ All images loaded');
// Initialize effect after images are ready
const fx = initCursorFX({ effect: 'bubble' });
})
.catch(err => {
console.warn('Failed to load images:', err);
// Effect will still work with canvas fallback
const fx = initCursorFX({ effect: 'bubble' });
});
<script src="https://unpkg.com/cursor-fx@latest/dist/cdn/cursor-fx.min.js"></script>
<script>
// Preload images from your server
CursorFX.ImageLoader.loadBubbles('/bubbles')
.then(() => {
// Initialize bubble effect with images
const fx = CursorFX.initCursorFX({ effect: 'bubble' });
});
</script>
// Load bubble images (expects 3 PNGs in the directory)
ImageLoader.loadBubbles(basePath?: string): Promise<HTMLImageElement[]>
// Load snowflake images (expects 2+ PNGs in the directory)
ImageLoader.loadSnowflakes(basePath?: string): Promise<HTMLImageElement[]>
// Load a single image
ImageLoader.loadImage(src: string): Promise<HTMLImageElement>
// Check if any images are loaded
ImageLoader.isLoaded(): boolean
// Clear all cached images
ImageLoader.clear(): void
Required file names:
soap_bubbles_1.png, soap_bubble_2.png, soap_bubble_3.pngsnow_flake_1.png, snow_flake_2.pngFallback Behavior: If images fail to load or aren't preloaded, bubble and snow effects automatically use optimized canvas rendering instead. Your effects will always work!
Included Assets:
Assets are bundled at dist/bubbles/ and dist/snowflakes/.
Each effect has themed default colors, but you can easily customize:
// Transparent pink bubbles
<CursorFX
effect="bubble"
colors={[
'rgba(255, 192, 203, 0.4)', // Pink
'rgba(255, 182, 193, 0.4)', // Light pink
]}
/>
// Blue-tinted snow
<CursorFX
effect="snow"
colors={['#E0FFFF', '#F0F8FF', '#F5FFFA']}
/>
// Custom sparkle colors
<CursorFX
effect="sparkle"
colors={['#FF0000', '#00FF00', '#0000FF']}
/>
throttle and minMoveDistance<CursorFX
effect="bubble"
throttle={200} // 200ms between spawns
minMoveDistance={20} // Spawn only after 20px movement
/>
<CursorFX effect="snow" particleCount={1} />
<CursorFX effect="sparkle" maxLife={15} />
const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
<CursorFX effect="bubble" enabled={!isMobile} />
function App() {
const [effect, setEffect] = useState('bubble');
return (
<>
<CursorFX effect={effect} />
<button onClick={() => setEffect('snow')}>Snow</button>
<button onClick={() => setEffect('bubble')}>Bubble</button>
<button onClick={() => setEffect('confetti')}>Confetti</button>
</>
);
}
const [config, setConfig] = useState({
particleCount: 2,
colors: ['#FFD700', '#FFC700']
});
<CursorFX effect="fairyDust" {...config} />
<button onClick={() => setConfig({...config, particleCount: 5})}>
More Particles
</button>
<CursorFX
effect="confetti"
enabled={isCelebrating}
particleCount={8}
/>
Works in all modern browsers that support:
Mobile Support: Touch events fully supported.
Performance Optimizations:
Optimized for minimal impact:
Dependencies:
Full TypeScript support included:
import type { CursorEffectType, EffectOptions } from 'cursor-fx';
import type { CursorFXProps } from 'cursor-fx/react';
const effect: CursorEffectType = 'bubble';
const options: EffectOptions = {
particleCount: 3,
colors: ['#FF0000']
};
Working examples included:
examples/react/ - Vite + React demoexamples/vanilla/ - Plain HTML demoRun examples:
cd examples/react
npm install
npm run dev
Contributions welcome! Please feel free to submit a Pull Request.
MIT © [Your Name]
Built with:
Made with ✨ by Anto Pravin C
FAQs
Beautiful, customizable cursor effects for React and vanilla JavaScript. Add magical fairy dust particles that follow your cursor with minimal setup.
We found that cursor-fx demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.
Security News
OpenSSF has issued a high-severity advisory warning open source developers of an active Slack-based campaign using impersonation to deliver malware.