Turn any interaction into a moment of joy* with zero-config Alpine.js directives for canvas-confetti.
* Disclaimer: actual joy may vary.
## ✨ Features
- **Three presets**: ` 🎉 $confetti()`, `✨ $starburst()`, and `💩 $emojify()`
- **Zero configuration**: Works out of the box with sensible defaults
- **Highly customizable**: Full access to `canvas-confetti` options
- **Smart positioning**: Automatically calculates element origins
- **Accessibility friendly**: Respects `prefers-reduced-motion`
- **TypeScript support**: Fully typed for better developer experience
## 👀 Interactive Demo
> See interactive examples [on the Demo page](https://jackwh.github.io/alpine-confetti/) ➡️
## 🚀 Quick Start
### CDN Installation
Add Alpine Confetti to your page via CDN:
```html
```
### NPM Installation
```bash
npm install @jackwh/alpine-confetti
```
Then register the plugin:
```javascript
import AlpineConfetti from '@jackwh/alpine-confetti';
document.addEventListener('alpine:init', () => {
AlpineConfetti(window.Alpine);
});
```
## 🔧 Usage
### Basic Confetti
The simplest way to add celebration to any element:
```html
🎉 Congrats, you're our 1,000,000th user!
```
### Starburst Effect
Perfect for achievements and special moments:
```html
```
### Custom Effects
You can change the particle count by providing a number: `$confetti(50)`. Or pass an object [with `canvas-confetti` options](https://github.com/catdad/canvas-confetti?tab=readme-ov-file#options) for more control:
```html
```
### Emojify
Because sometimes regular particles just won't do...
```html
🎂 Happy Birthday to you!
```
## 🎨 Creative Example
There are lots of ways to use confetti effects interactively.
Here's just one example, check out the rest on the [Demo page](https://jackwh.github.io/alpine-confetti/) for more ➡️
```html
```
See the [Demo page](https://jackwh.github.io/alpine-confetti/) to try this out.
## 🎛️ API Reference
### `$confetti(options?)`
Creates a burst of confetti from the element.
- **Parameter**: `number | Options` - Particle count or full options object
- **Default**: 100 particles with colorful confetti
### `$starburst(options?)`
Creates a starburst effect with star-shaped particles.
- **Parameter**: `number | Options` - Particle count or full options object
- **Default**: 10 yellow star particles in all directions
### `$emojify(emojis, options?)`
Creates confetti using custom emoji shapes.
- **Parameters**:
- `emojis`: `string[]` - Array of emoji to use as particles
- `options`: `number | Options` - Particle count or full options object
- **Default**: `['🍓', '🍌', '🥝']` with 10 particles
## ⚙️ Configuration Options
All methods accept the full range of [canvas-confetti options](https://github.com/catdad/canvas-confetti?tab=readme-ov-file#options). Here's a quick reference for the most commonly used ones:
```javascript
{
particleCount: 100, // Number of particles
angle: 90, // Direction in degrees
spread: 45, // Spread in degrees
startVelocity: 45, // Initial velocity
decay: 0.9, // Particle decay rate
gravity: 1, // Gravity strength
drift: 0, // Side-to-side drift
ticks: 200, // Particle lifetime
colors: ['#fff'], // Color array
scalar: 1 // Size multiplier
}
```
The plugin respects the `prefers-reduced-motion` media query by default. Users with motion sensitivity won't see the animations.
## 🙏 Credits
- 🎊 [canvas-confetti](https://github.com/catdad/canvas-confetti)
- ⛰️ [Alpine.js](https://alpinejs.dev)
- 🎨 [Tailwind CSS](http://tailwindcss.com) (for demo styles)
- 😎 [Jack Webb-Heller](https://github.com/jackwh)
- 🫵 You? Contributions are welcome!
