Physics-based confetti celebrations with fluid dynamics, haptic feedback, and procedural audio. Built with hexgrid-3d math.
npm install @affectively/confetti-physicsPhysics-based confetti celebrations with fluid dynamics, haptic feedback, and procedural audio. Built with hexgrid-3d math.
- 🌀 Physics-based confetti - Fluid dynamics, flow fields, and particle attractors
- 🎉 Classic confetti - Traditional particle effects via canvas-confetti
- 🔊 Procedural audio - Web Audio API tones (no audio files needed)
- 📳 Haptic feedback - Web Vibration API patterns
- ⚛️ React hooks - Easy integration with React apps
- ♿ Accessibility - Respects prefers-reduced-motion
- 💾 Preference persistence - User settings saved to localStorage
``bash`
npm install @affectively/confetti-physicsor
yarn add @affectively/confetti-physicsor
bun add @affectively/confetti-physics
`typescript
import { CelebrationService, ConfettiService, SoundService, HapticService } from '@affectively/confetti-physics';
// Quick celebration with confetti + sound + haptic
CelebrationService.celebrate('achievement');
// Physics-based confetti only
ConfettiService.supernova();
ConfettiService.aurora();
ConfettiService.vortex();
// Individual services
SoundService.success();
HapticService.celebrate();
`
`tsx
import { useCelebration, useConfetti, usePhysicsConfetti } from '@affectively/confetti-physics/react';
function MyComponent() {
const { celebrate, success, milestone } = useCelebration();
const confetti = useConfetti();
return (
Celebration Types
$3
combines confetti, sound, and haptic feedback:| Type | Confetti | Sound | Haptic |
|------|----------|-------|--------|
|
tap | - | tap | light |
| success | - | success | medium |
| complete | sparkles | complete | medium |
| achievement | achievement | milestone | strong |
| milestone | milestone | milestone | strong |
| streak | burst | streak | medium |
| streakMilestone | streak | celebration | strong |
| levelUp | levelUp | levelUp | strong |
| unlock | stars | unlock | strong |
| premium | premium | celebration | strong |
| welcome | welcome | success | medium |
| error | - | error | medium |
| warning | - | warning | light |$3
| Type | Description |
|------|-------------|
|
burst | Quick celebration burst |
| shower | Confetti rain from top |
| fireworks | Firework explosions |
| sparkles | Gentle sparkle effect |
| stars | Star-shaped particles |
| hearts | Heart emoji particles |
| achievement | Grand achievement celebration |
| streak | Fire + gold confetti |
| milestone | Trophy + stars |
| levelUp | Rocket + fireworks |
| welcome | Gentle welcome |
| premium | Crown + gem + gold |$3
These use fluid dynamics, flow fields, and attractors from hexgrid-3d:
| Type | Description |
|------|-------------|
|
vortex | Spiral vortex pulling particles inward |
| supernova | Explosive burst with fluid shockwave |
| aurora | Flowing northern lights ribbons |
| resonance | Heart-rate synced pulsing |
| orbit | Particles orbiting multiple attractors |
| cascade | Fluid waterfall effect |
| emergence | Particles following flow field |
| harmony | Lissajous pattern attractors |
| helix | DNA-like double helix spiral |
| bloom | Flower-like unfolding pattern |
| constellation | Particles forming and connecting |
| nebula | Gas cloud effect with density |Emotion-Aware Celebrations
Automatically select effects and colors based on emotional context:
`typescript
import { ConfettiService } from '@affectively/confetti-physics';ConfettiService.celebrateEmotion({
emotion: 'joy',
valence: 0.8, // -1 to 1 (negative to positive)
arousal: 0.7, // 0 to 1 (calm to excited)
heartRate: 80 // Optional: sync with biometrics
});
`$3
| Emotion | Colors |
|---------|--------|
| joy | Gold, amber |
| serenity | Emerald, mint |
| excitement | Rose, gold |
| love | Pink, rose |
| triumph | Purple, gold |
| gratitude | Teal, emerald |
| wonder | Sky blue, purple |
| peace | Green, teal |
Sound Effects
14 procedurally generated sounds using Web Audio API:
typescript
import { SoundService } from '@affectively/confetti-physics';SoundService.tap(); // Soft click
SoundService.success(); // C5-E5-G5 ascending
SoundService.celebration(); // Full fanfare
SoundService.milestone(); // Grand achievement
SoundService.streak(); // Quick excitement
SoundService.levelUp(); // Ascending scale
SoundService.unlock(); // Unlocking tone
SoundService.complete(); // Task done
SoundService.breatheIn(); // Rising tone for breathing exercises
SoundService.breatheOut(); // Falling tone
SoundService.heartbeat(); // Lub-dub rhythm
SoundService.error(); // Descending tone
SoundService.warn(); // Alert tone
`$3
typescript
SoundService.setVolume(0.5); // 0-1
SoundService.setEnabled(false); // Mute
`Haptic Feedback
15 vibration patterns via Web Vibration API:
typescript
import { HapticService } from '@affectively/confetti-physics';HapticService.tap('light'); // Light tap
HapticService.success('medium'); // Satisfying success
HapticService.celebrate('strong'); // Excitement burst
HapticService.milestone(); // Grand achievement
HapticService.streak(); // Rapid fire
HapticService.levelUp(); // Ascending power
HapticService.unlock(); // Unlocking sensation
HapticService.heartbeat(); // Calming heartbeat
HapticService.breatheIn(); // For breathing exercises
HapticService.breatheOut();
`$3
-
- 50% duration multiplier
- medium - 100% (default)
- strong - 150%User Preferences
Preferences are automatically saved to localStorage:
`typescript
import { CelebrationService } from '@affectively/confetti-physics';// Get current settings
const settings = CelebrationService.getSettings();
// { soundEnabled, hapticEnabled, confettiEnabled, volume, hapticSupported, soundSupported }
// Update settings
CelebrationService.setSoundEnabled(false);
CelebrationService.setHapticEnabled(true);
CelebrationService.setConfettiEnabled(true);
CelebrationService.setVolume(0.7);
// Enable/disable all at once
CelebrationService.enableAll();
CelebrationService.disableAll();
`React Hooks
$3
Main hook for all celebration functionality:
tsx
const {
celebrate, // (type) => void
celebrateCustom, // (config) => void
celebrateStreak, // (days) => void
tap, success, complete, achievement, milestone,
levelUp, unlock, premium, welcome, error, warning,
settings, // Current settings
setSoundEnabled, setHapticEnabled, setConfettiEnabled, setVolume
} = useCelebration();
`$3
For visual celebrations:
tsx
const {
celebrate, // (type) => void
celebratePhysics, // (config) => void
celebrateEmotion, // ({ emotion, valence, arousal }) => void
enabled, setEnabled,
physicsEnabled, setPreferPhysics,
fromElement, // (element, type?) => void
reset, // () => void
// Classic: burst, shower, fireworks, sparkles, stars, hearts, etc.
// Physics: vortex, supernova, aurora, resonance, orbit, cascade, etc.
} = useConfetti();
`$3
Direct access to physics engine:
tsx
const {
celebrate, // (config) => void
celebrateWithEmotion, // (type, emotion, options) => void
clear, // () => void
enabled, setEnabled,
isAvailable,
// Each type as a method with optional config
vortex, supernova, aurora, resonance, orbit, cascade,
emergence, harmony, helix, bloom, constellation, nebula
} = usePhysicsConfetti();
`$3
Individual service hooks:
tsx
const sound = useSound();
const haptic = useHaptic();// Both have:
// - enabled, supported, setEnabled
// - Convenience methods (tap, success, etc.)
`$3
For button feedback:
tsx
const { onPress, onSuccess, onError } = useInteractionFeedback();
`$3
For breathing exercises:
tsx
const { breatheIn, breatheOut, hold, complete, breathingCycle } = useBreathingFeedback();
`$3
For streak milestones:
tsx
const { celebrateStreak, celebrateDaily, celebrateWeekly } = useStreakCelebration();// celebrateStreak(days) automatically picks the right celebration:
// - Day 1: dailyCheckIn
// - Days 7, 30, 100, 365: streakMilestone
// - Other days: streak
`Accessibility
The library automatically respects
:`css
@media (prefers-reduced-motion: reduce) {
/ Confetti and animations are disabled /
}
`You can also manually disable effects:
typescript
CelebrationService.disableAll();
// or individually:
ConfettiService.setEnabled(false);
SoundService.setEnabled(false);
HapticService.setEnabled(false);
`Browser Support
| Feature | Browser Support |
|---------|-----------------|
| Confetti (canvas) | All modern browsers |
| Physics engine | All modern browsers |
| Web Audio API | All modern browsers |
| Vibration API | Android Chrome, Firefox |
Dependencies
- Physics math (fluid dynamics, flow fields)
- canvas-confetti - Classic confetti effects
- react` (peer, optional) - For React hooksMIT © AFFECTIVELY
Contributions are welcome! Please read our contributing guidelines first.
- hexgrid-3d - The math library powering the physics
- canvas-confetti - Classic confetti effects