{"id":15175,"library":"react-canvas-confetti","title":"React Canvas Confetti","description":"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.","status":"active","version":"2.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/ulitcos/react-canvas-confetti","tags":["javascript","react","canvas","confetti","animation","burst","fireworks","snow","particles","typescript"],"install":[{"cmd":"npm install react-canvas-confetti","lang":"bash","label":"npm"},{"cmd":"yarn add react-canvas-confetti","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-canvas-confetti","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for any React component library.","package":"react","optional":false}],"imports":[{"note":"Presets like `Fireworks` are deep imports from the `dist/presets` directory. This is not a named export from the root package.","wrong":"import { Fireworks } from 'react-canvas-confetti';","symbol":"Fireworks","correct":"import Fireworks from 'react-canvas-confetti/dist/presets/fireworks';"},{"note":"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.","wrong":"import { ReactCanvasConfetti } from 'react-canvas-confetti';","symbol":"ReactCanvasConfetti","correct":"import ReactCanvasConfetti from 'react-canvas-confetti';"},{"note":"Use `import type` for type-only imports in TypeScript to avoid bundling type definitions into your runtime code.","wrong":"import { TConductorInstance } from 'react-canvas-confetti';","symbol":"TConductorInstance","correct":"import type { TConductorInstance } from 'react-canvas-confetti';"}],"quickstart":{"code":"import React, { useRef, useCallback, useState } from 'react';\nimport Fireworks from 'react-canvas-confetti/dist/presets/fireworks';\nimport type { TConductorInstance } from 'react-canvas-confetti';\n\nfunction ConfettiDemo() {\n  const conductorRef = useRef<TConductorInstance | null>(null);\n  const [isRunning, setIsRunning] = useState(false);\n\n  const onInit = useCallback(({ conductor }: { conductor: TConductorInstance }) => {\n    conductorRef.current = conductor;\n    // You could autorun here as well, but we'll use a button for demonstration\n    // conductor.run({ speed: 2 });\n    // setIsRunning(true);\n  }, []);\n\n  const handleShootConfetti = useCallback(() => {\n    if (conductorRef.current) {\n      conductorRef.current.shoot();\n    }\n  }, []);\n\n  const handleRunAnimation = useCallback(() => {\n    if (conductorRef.current) {\n      conductorRef.current.run({ speed: 1.5, duration: 2000 });\n      setIsRunning(true);\n    }\n  }, []);\n\n  const handleStopAnimation = useCallback(() => {\n    if (conductorRef.current) {\n      conductorRef.current.stop();\n      setIsRunning(false);\n    }\n  }, []);\n\n  return (\n    <div>\n      <h1>Confetti Show!</h1>\n      <p>Click buttons to control the fireworks animation.</p>\n      <button onClick={handleShootConfetti} style={{ margin: '10px', padding: '10px 20px' }}>\n        Single Burst\n      </button>\n      <button onClick={handleRunAnimation} disabled={isRunning} style={{ margin: '10px', padding: '10px 20px' }}>\n        Start Continuous\n      </button>\n      <button onClick={handleStopAnimation} disabled={!isRunning} style={{ margin: '10px', padding: '10px 20px' }}>\n        Stop Continuous\n      </button>\n      {/* The Fireworks component will render the canvas */}\n      <Fireworks onInit={onInit} autorun={false} />\n      <p style={{ marginTop: '20px' }}>\n        This example demonstrates how to control the confetti animation manually using the `ConductorInstance`\n        obtained via the `onInit` callback of the `Fireworks` preset component.\n        It shows single bursts and continuous animation, offering full control over the visual effects.\n      </p>\n    </div>\n  );\n}\n\nexport default ConfettiDemo;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure `react` and `react-dom` are installed: `npm install react react-dom`.","message":"The `react` package is a peer dependency and must be installed separately in your project. Failing to do so will result in runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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} />`.","message":"For 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify the exact import path for the preset you are trying to use. Presets are typically located under `dist/presets/`.","cause":"Incorrect import path for a preset component, or the file does not exist at the specified location.","error":"Error: Can't resolve 'react-canvas-confetti/dist/presets/fireworks'"},{"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.","cause":"This usually indicates an attempt to `require` a default ESM export incorrectly or a mismatch between CommonJS and ES Module import styles.","error":"TypeError: (0 , _reactCanvasConfetti.default) is not a function"},{"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.","cause":"React is not imported or available in the scope where JSX is being used.","error":"Uncaught ReferenceError: React is not defined"}],"ecosystem":"npm"}