yolabs-confetti-engine
v1.0.2
Published
Enterprise-grade high-performance confetti engine with Web Worker physics.
Maintainers
yonas2754Readme
🚀 yolabs-confetti-engine
The high-performance confetti physics engine for React 18+ and Next.js.
By offloading all physics calculations to a Web Worker, YOLABS ensures your UI remains responsive at 60FPS, even during massive explosions. No main-thread lag, no matter how many particles you fire.
🛠 1. Installation
npm install yolabs-confetti-engine
🏗 2. Setup (Global)
For Next.js (App Router)
Next.js renders components on the server by default. To avoid createContext errors, wrap the provider in a Client Component wrapper.
- Create
components/ConfettiWrapper.tsx:
"use client";
import { ConfettiProvider } from "yolabs-confetti-engine";
export default function ConfettiWrapper({ children }) {
return <ConfettiProvider>{children}</ConfettiProvider>;
}
- Add to
app/layout.tsx:
import ConfettiWrapper from "@/components/ConfettiWrapper";
export default function RootLayout({ children }) {
return (
<html>
<body>
<ConfettiWrapper>{children}</ConfettiWrapper>
</body>
</html>
);
}
For Standard React (Vite / CRA)
In a standard SPA, you can wrap your app directly in the entry point.
Edit src/main.tsx (or index.js):
import { ConfettiProvider } from 'yolabs-confetti-engine';
ReactDOM.createRoot(document.getElementById('root')!).render(
<ConfettiProvider>
<App />
</ConfettiProvider>
);
🎉 3. Usage
Trigger confetti from any component using the useConfetti hook.
Note for Next.js: The component calling useConfetti must include the "use client" directive.
"use client";
import { useConfetti } from "yolabs-confetti-engine";
export default function WinButton() {
const { fire } = useConfetti();
const handleWin = () => {
fire('boom', {
particleCount: 150,
colors: ['#FFD700', '#FFFFFF'],
iterations: 1
});
};
return <button onClick={handleWin}>Celebrate!</button>;
}
🕹 Usage Menu (Patterns)
The fire(type, options) function supports various physics behaviors:
| Pattern | Behavior |
| --- | --- |
| 'boom' | Radial explosion from the center (or custom origin). |
| 'fountain' | Upward spray that arcs gracefully downward. |
| 'rain' | Continuous particles falling from the top. |
| 'spiral' | Circular, expanding physics movement. |
Configuration Options (opt)
| Property | Type | Description |
| --- | --- | --- |
| particleCount | number | Number of particles per burst. |
| iterations | number | Number of times the burst repeats. |
| delay | number | Delay in milliseconds between repetitions. |
| gravity | number | Speed of descent (lower = lighter/floatier). |
| colors | string[] | Array of hex color strings (e.g., #FF0000). |
| shapes | string[] | Mix star, circle, square, or triangle. |
⚙️ Advanced: Automatic Triggers
Perfect for games. Use useEffect to trigger celebrations when a score or state changes:
const { fire } = useConfetti();
useEffect(() => {
if (score >= 100) {
fire('fountain', { iterations: 3, delay: 500 });
}
}, [score]);
📄 License
Licensed under the MIT License.
🤝 Credits
Developed by **YOLABS **. Optimized for modern React performance and off-main-thread execution.
Auther by yonas