celebrate-js 🎉

A lightweight, zero-dependency JavaScript library to add beautiful celebration effects to your website - confetti, fireworks, balloons, emoji rain, and more.

Perfect for success screens, onboarding, achievements, or fun UI moments.

Features

• Multiple celebration effects
• Customizable colors 🎨
• Built-in and custom sound support
• Lightweight and fast
• Simple API
• TypeScript support
• Optional reduced-motion support

Installation

npm install celebrate-js

or

yarn add celebrate-js

Usage

import { celebrate } from "celebrate-js";

// Default: confetti
celebrate();

// Use a specific effect
celebrate.confetti();
celebrate.balloons({ particleCount: 20 });
celebrate.fireworks({ count: 6 });
celebrate.stars({ sound: true });
celebrate.popper({ sound: "/sounds/success.mp3" });

Effects

Confetti

Small flat squares falling from the top of the screen.

celebrate.confetti({
  duration: 2000,
  particleCount: 150,
  colors: ["#4285F4", "#34A853", "#FBBC05", "#EA4335"],
  sound: true
});

You can change:

• duration - how long the animation runs
• particleCount - number of pieces
• colors - colors used per piece
• sound - built-in chime or custom audio path

Balloons

Flat balloons rising from the bottom of the screen.

celebrate.balloons({
  duration: 3000,
  particleCount: 20,
  colors: ["#4285F4", "#34A853", "#FBBC05", "#EA4335"],
  sound: true
});

You can change:

• duration - how long balloons keep rising
• particleCount - number of balloons
• colors - colors used per balloon
• sound - built-in chime or custom audio path

Popper

Confetti bursts from both bottom sides of the screen.

celebrate.popper({
  duration: 3200,
  particleCount: 120,
  colors: ["#4285F4", "#34A853", "#FBBC05", "#EA4335"],
  sound: "/sounds/success.mp3"
});

You can change:

• duration - how long the burst runs
• particleCount - number of particles
• colors - colors used per particle
• sound - built-in chime or custom audio path

Fireworks

Circular bursts that appear across the upper half of the screen.

celebrate.fireworks({
  duration: 4000,
  count: 5,
  interval: 500,
  colors: ["#4285F4", "#34A853", "#FBBC05", "#EA4335"]
});

You can change:

• duration - total animation time
• count - number of bursts
• interval - delay between bursts in milliseconds
• colors - colors used per burst
• sound - built-in chime or custom audio path

Bubbles

Soft bubbles floating upward.

celebrate.bubbles({
  duration: 3000,
  particleCount: 25
});

You can change:

• duration - how long bubbles keep floating
• particleCount - number of bubbles
• sound - built-in chime or custom audio path

Emojis

Emoji rain falling from the top of the screen.

celebrate.emojis({
  duration: 3000,
  particleCount: 30,
  emojis: ["🎉", "✨", "🔥", "💯", "😍"]
});

You can change:

• duration - how long emojis fall
• particleCount - number of emojis
• emojis - custom emoji list
• sound - built-in chime or custom audio path

Stars

Shooting stars crossing the screen.

celebrate.stars({
  duration: 3000,
  count: 5,
  interval: 500
});

You can change:

• duration - total animation time
• count - number of shooting stars
• interval - delay between stars in milliseconds
• sound - built-in chime or custom audio path

Snowfall

Light snow falling from the top of the screen.

celebrate.snowfall({
  duration: 5000,
  particleCount: 60
});

You can change:

• duration - how long snow keeps falling
• particleCount - number of flakes
• sound - built-in chime or custom audio path

API

celebrate(options?)

celebrate({
  effect: "confetti",
  duration: 5000,
  particleCount: 100,
  colors: ["#ff0", "#0ff"],
  sound: true,
  soundVolume: 0.35
});

Shortcuts

celebrate.confetti(options);
celebrate.balloons(options);
celebrate.popper(options);
celebrate.fireworks(options);
celebrate.bubbles(options);
celebrate.emojis(options);
celebrate.stars(options);
celebrate.snowfall(options);

Options

type CelebrateOptions = {
  effect?: "confetti" | "balloons" | "popper" | "fireworks" | "bubbles" | "emojis" | "stars" | "snowfall";
  duration?: number;
  particleCount?: number;

  /**
   * Colors used by supported effects (confetti, balloons, fireworks, popper, stars)
   */
  colors?: string[];

  respectReducedMotion?: boolean;
  sound?: boolean | string;
  soundVolume?: number;

  // Fireworks only
  count?: number;
  interval?: number;

  // Emoji rain only
  emojis?: string[];
};

Defaults use a modern flat Google-style palette:

["#4285F4", "#34A853", "#FBBC05", "#EA4335"]

Sound

Sound works with every effect and is off by default.

Use the built-in completion chime:

celebrate.balloons({
  sound: true
});

Use your own audio file by passing a path or URL:

celebrate.balloons({
  sound: "/sounds/success.mp3"
});

In Vite, files inside public/ are served from the root:

public/success.mp3 -> /success.mp3

Adjust volume:

celebrate.fireworks({
  sound: "/sounds/success.mp3",
  soundVolume: 0.2
});

Sound is off by default. Browsers usually require sound to start from a user action, like a button click.

Reduced Motion

If respectReducedMotion is enabled and the user has prefers-reduced-motion set, animations will be skipped.

celebrate({
  respectReducedMotion: true
});

Local Demo

npm run dev

Open http://localhost:5173/ and click the demo button.

License

MIT © Akshay Yadav