Make a little
firework magic.

01 / INSTALL

Install the package

Add the package to your project via npm.

npm

npm install shoka-fireworks

02 / CUSTOMIZE & PREVIEW

Tune your firework palette

Add or tweak colors and test them live. The integration snippet below updates automatically.

Color palette

Pick a swatch or enter any CSS color value. Changes apply to the next firework.

Interactive preview

Live preview

Click inside the canvas below to test your palette.

03 / INTEGRATE

Add to your site

Run this code in the browser once document.body is ready (for example, inside your component’s mount hook). Your custom palette is already filled in.

import { fireworks } from "shoka-fireworks";

const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
const cleanup = fireworks({
  shouldPlayAnimation: () => !reducedMotion.matches,
});

// When unmounting or disabling the effect, call cleanup() to stop animations and remove listeners.

shouldPlayAnimation checks reducedMotion.matches on every click; when Reduced Motion is enabled, it returns false so no new fireworks are triggered.

Fireworks already in flight finish playing naturally. To stop all animations immediately and remove the effect (such as on component unmount), call cleanup().

04 / API REFERENCE

`fireworks(config?: FireworkConfig): () => void`

Call in the browser once document.body is ready. Each call returns its own cleanup function.

`FireworkConfig`

Option	Type	Default	Behavior
`colors?`	`string[]`	The 4 default pastel colors below	CSS color strings for firework particles. Must include at least 1 color.
`shouldPlayAnimation?`	`(event: MouseEvent) => boolean`	`() => true`	Triggered on every click. Return `false` to skip the firework for that click without interrupting active animations.

The library does not check Reduced Motion automatically. Check it inside shouldPlayAnimation as shown in the example above.

Default palette

[
  "rgba(255,182,185,.9)",
  "rgba(250,227,217,.9)",
  "rgba(187,222,214,.9)",
  "rgba(138,198,209,.9)"
]

Cleanup & teardown

When unmounting a component or disabling the effect, call the cleanup function returned by fireworks() to stop all animations, remove the canvas, and detach click and resize listeners.

cleanup();

Credits

This library’s fireworks effect is adapted from Hexo Theme Shoka. Thank you to the original author, 霜月琉璃.