repository·master·Indexed 42 days ago
https://github.com/ulitcos/react-canvas-confettiA React wrapper for the canvas-confetti library (v2.0.7) that provides a React component interface for confetti effects. It includes a base ReactCanvasConfetti component for direct instance control and several high-level animation presets such as Fireworks, Explosion, Snow, Pride, Realistic, Photons, and Crossfire, which can be managed via a Conductor instance.
canvas-confetti instance. This is a lower-level approach. You can access the confetti instance through the onInit callback.If you are using presets, you can manually control animations (start, stop, pause) using a Conductor instance. You can access this instance via the onInit callback prop.
type TRunAnimationParams = {
speed: number;
duration?: number;
delay?: number;
};
type TConductorInstance = {
run: (params: TRunAnimationParams) => void;
shoot: () => void;
pause: () => void;
stop: () => void;
};Presets are the recommended way to use the module. They are animation templates that are ready to use. While you can customize animation settings, you cannot change the underlying animation algorithm.
To use a preset, import it from the dist/presets directory and pass an autorun prop to start the animation immediately upon mounting.
import Fireworks from "react-canvas-confetti/dist/presets/fireworks";
function Example() {
return <Fireworks autorun={{ speed: 3 }} />;
}
export default Example;Install the package using npm. Note that react must already be installed as a peer dependency in your project.
npm i react-canvas-confettiThese settings are common to all use cases (both presets and direct instance usage).
| Name | Type | Description |
| ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| width | string \| number | value is responsible for the width of the canvas. Alternative ways to control canvas sizes are className and style props. |
| height | string \| number | value is responsible for the height of the canvas. Alternative ways to control canvas sizes are className and style props. |
| className | string | value to set className to canvas element |
| style | CSSProperties | value to set style to canvas element. If `style` and `className` are not passed, the default styles will be set. |
| globalOptions | [TGlobalOptions] | global animation settings that cannot be changed after initialization. |
| onInit | (params: {confetti: TCanvasConfettiInstance}) => void | the callback is called when the component is mounted on the page and allows you to access confetti instance. |These settings are exclusive to presets and allow for deeper customization of the animation behavior.
| Name | Type | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| autorun | { speed: number; duration?: number; delay?: number; } | if it is passed, it automatically starts the animation when mounting the component on the page. |
| decorateOptions | (options: TOptions) => TOptions | the callback allows you to customize the animation settings and is called for each step of the animation. |
| onInit | (params: { confetti: TCanvasConfettiInstance; conductor: TConductorInstance }) => void | the callback is called when the component is mounted on the page and allows you to access objects for manual creation and animation control. | The ReactCanvasConfetti component provides a React wrapper around the canvas-confetti library. It renders a <canvas> element that covers the viewport by default (using position: fixed, pointer-events: none, etc.) and manages the lifecycle of the confetti instance.
To use it, you can pass configuration via globalOptions and access the underlying confetti instance through the onInit callback.
import ReactCanvasConfetti from 'react-canvas-confetti';
function MyComponent() {
return (
<ReactCanvasConfetti
onInit={({ confetti }) => {
// Use the confetti instance to trigger effects
confetti.create({ /* options */ });
}}
/>
);
}The Preset component is a high-level abstraction that combines ReactCanvasConfetti with a Conductor class to manage complex, orchestrated confetti sequences.
Instead of manually triggering confetti bursts, you provide a Conductor (a class that defines how confetti behaves over time) and an optional autorun configuration. The Preset component handles the lifecycle of the confetti instance, initializes the conductor, and can automatically start the animation sequence.
Key props:
Conductor: A class used to orchestrate the confetti effects.autorun: An optional configuration passed to conductor.run() to start the effect automatically.decorateOptions: A function (o) => o used to decorate options before they are passed to the conductor.onInit: A callback invoked with { confetti, conductor } once the confetti instance and conductor are ready.onInit (on ReactCanvasConfetti): Note that Preset uses the underlying onInit of ReactCanvasConfetti to capture the TCanvasConfettiInstance.// Example conceptual usage of the Preset component
<Preset
Conductor={MyCustomConductor}
autorun={{ duration: 5 }}
onInit={({ confetti, conductor }) => {
console.log('Conductor is ready');
}}
/>Parameters used to control the timing and velocity of a confetti animation run.
type TRunAnimationParams = {
speed: number;
duration?: number;
delay?: number;
};The ReactCanvasConfetti component accepts the following props:
| Prop | Type | Description |
|---|---|---|
style | CSSProperties | Custom styles for the canvas element. If not provided, it defaults to a fixed, full-screen overlay with pointer-events: none. |
className | string | CSS class name for the canvas element. |
width | number | The width of the canvas. |
height | number | The height of the canvas. |
globalOptions | TCanvasConfettiGlobalOptions | Options passed to the canvas-confetti instance creation. Includes resize (default true) and useWorker (default false). |
onInit | (data: { confetti: TCanvasConfettiInstance }) => void | A callback function invoked once the confetti instance is initialized. Provides access to the confetti instance. |
The Crossfire component is a specialized preset provided by react-canvas-confetti. It uses the CrossfireConductor to manage the confetti animation logic. You can use it by passing standard TPresetInstanceProps to control the animation behavior.
import Crossfire from 'react-canvas-confetti/presets/crossfire';
// Usage within a React component
<Crossfire
// props follow TPresetInstanceProps
/>The TDecorateOptionsFn is a callback used to intercept and modify the confetti animation options before they are applied. It receives the current TCanvasConfettiAnimationOptions and must return a modified version of those options.
import { TDecorateOptionsFn } from 'react-canvas-confetti';
const myDecorator: TDecorateOptionsFn = (options) => {
return {
...options,
// Modify specific animation properties here
};
};