Registry / web-framework / react-canvas-confetti

react-canvas-confetti

JSON →
library2.0.7jsnpmunverified

react-canvas-confetti provides a React-friendly interface for the popular canvas-confetti library, enabling developers to easily integrate various confetti, fireworks, and particle animations into their applications. As of version 2.0.7, it offers two primary usage patterns: a simplified preset system (e.g., `Fireworks`) for common animation templates with customizable settings, and a lower-level API that grants direct access to the `canvas-confetti` instance for creating bespoke animation algorithms. The library ships with TypeScript types, promoting robust development. While no explicit release cadence is documented, its active GitHub repository and npm download statistics suggest consistent maintenance and updates, typically aligning with the underlying `canvas-confetti` library's evolution and React ecosystem best practices. It differentiates itself by abstracting away direct DOM manipulation for canvas elements, providing a declarative component-based approach.

npm install react-canvas-confetti
INSTALL
IMPORT
SIG · REACT-CANVAS-CONFE
R
react-canvas-confetti
web-frameworkjavascriptv2.0.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Fireworks
import Fireworks from 'react-canvas-confetti/dist/presets/fireworks';
import { Fireworks } from 'react-canvas-confetti';
Presets like `Fireworks` are deep imports from the `dist/presets` directory. This is not a named export from the root package.
ReactCanvasConfetti
import ReactCanvasConfetti from 'react-canvas-confetti';
import { ReactCanvasConfetti } from 'react-canvas-confetti';
This is the default export for the base component, used when you want to access the raw `canvas-confetti` instance via the `onInit` prop or use more advanced control.
TConductorInstance
import type { TConductorInstance } from 'react-canvas-confetti';
import { TConductorInstance } from 'react-canvas-confetti';
Use `import type` for type-only imports in TypeScript to avoid bundling type definitions into your runtime code.

This quickstart demonstrates how to integrate the `Fireworks` preset component and manually control its animation using the `ConductorInstance` obtained from the `onInit` callback. It showcases single bursts and continuous firing patterns.

import React, { useRef, useCallback, useState } from 'react'; import Fireworks from 'react-canvas-confetti/dist/presets/fireworks'; import type { TConductorInstance } from 'react-canvas-confetti'; function ConfettiDemo() { const conductorRef = useRef<TConductorInstance | null>(null); const [isRunning, setIsRunning] = useState(false); const onInit = useCallback(({ conductor }: { conductor: TConductorInstance }) => { conductorRef.current = conductor; // You could autorun here as well, but we'll use a button for demonstration // conductor.run({ speed: 2 }); // setIsRunning(true); }, []); const handleShootConfetti = useCallback(() => { if (conductorRef.current) { conductorRef.current.shoot(); } }, []); const handleRunAnimation = useCallback(() => { if (conductorRef.current) { conductorRef.current.run({ speed: 1.5, duration: 2000 }); setIsRunning(true); } }, []); const handleStopAnimation = useCallback(() => { if (conductorRef.current) { conductorRef.current.stop(); setIsRunning(false); } }, []); return ( <div> <h1>Confetti Show!</h1> <p>Click buttons to control the fireworks animation.</p> <button onClick={handleShootConfetti} style={{ margin: '10px', padding: '10px 20px' }}> Single Burst </button> <button onClick={handleRunAnimation} disabled={isRunning} style={{ margin: '10px', padding: '10px 20px' }}> Start Continuous </button> <button onClick={handleStopAnimation} disabled={!isRunning} style={{ margin: '10px', padding: '10px 20px' }}> Stop Continuous </button> {/* The Fireworks component will render the canvas */} <Fireworks onInit={onInit} autorun={false} /> <p style={{ marginTop: '20px' }}> This example demonstrates how to control the confetti animation manually using the `ConductorInstance` obtained via the `onInit` callback of the `Fireworks` preset component. It shows single bursts and continuous animation, offering full control over the visual effects. </p> </div> ); } export default ConfettiDemo;
Debug
Known issues
gotchaThe `react` package is a peer dependency and must be installed separately in your project. Failing to do so will result in runtime errors.
fix
Ensure `react` and `react-dom` are installed: `npm install react react-dom`.
affects: >=1.0.0
gotchaWhen using the `useWorker: true` option (inherent from `canvas-confetti`), the canvas control is transferred to a web worker. Direct manipulation of the canvas element from the main thread will cause errors.
fix
Avoid direct DOM manipulation of the canvas element if `useWorker` is enabled. Control confetti animations exclusively through the component's props or the `canvas-confetti` instance's API.
affects: >=1.0.0
gotchaFor optimal performance and responsiveness, it is recommended to explicitly set the `width` and `height` props on the confetti component, or manage the canvas sizing through CSS. Default sizing might not react to window resizes without additional configuration.
fix
Pass `width` and `height` props to the component or ensure the canvas container has defined dimensions. E.g., `<Fireworks width={window.innerWidth} height={window.innerHeight} />`.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Can't resolve 'react-canvas-confetti/dist/presets/fireworks'
Incorrect import path for a preset component, or the file does not exist at the specified location.
fix
Verify the exact import path for the preset you are trying to use. Presets are typically located under `dist/presets/`.
TypeError: (0 , _reactCanvasConfetti.default) is not a function
This usually indicates an attempt to `require` a default ESM export incorrectly or a mismatch between CommonJS and ES Module import styles.
fix
If using CommonJS, ensure you're importing `ReactCanvasConfetti` correctly. If using ESM, make sure to use `import ReactCanvasConfetti from 'react-canvas-confetti';` for the default export.
Uncaught ReferenceError: React is not defined
React is not imported or available in the scope where JSX is being used.
fix
Add `import React from 'react';` at the top of your component file, especially if using older React versions or specific build configurations. For newer React (17+ with new JSX transform), this is often not required, but can still be a symptom of a misconfigured build or missing peer dependency.
Upgrade
Version history
2.0.7latest on npm
Audit
Dependencies
reactrequiredPeer dependency required for any React component library.
Agent activity
2 hits · last 30 days
node
2
Resources
react-canvas-confetti — npm install react-canvas-confetti · libregistry