React Canvas Confetti

Common errors

• Error: Can't resolve 'react-canvas-confetti/dist/presets/fireworks'

  cause 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

  cause 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

  cause 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.

Warnings

• gotcha The `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`.
• gotcha 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.
  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.
• gotcha 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.
  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} />`.

Install

• npm install react-canvas-confetti npm
• yarn add react-canvas-confetti yarn
• pnpm add react-canvas-confetti pnpm

Imports

• Fireworks
  wrong:

  import { Fireworks } from 'react-canvas-confetti';

  correct:

  import Fireworks from 'react-canvas-confetti/dist/presets/fireworks';

  Presets like `Fireworks` are deep imports from the `dist/presets` directory. This is not a named export from the root package.
• ReactCanvasConfetti
  wrong:

  import { ReactCanvasConfetti } from 'react-canvas-confetti';

  correct:

  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
  wrong:

  import { TConductorInstance } from 'react-canvas-confetti';

  correct:

  import type { TConductorInstance } from 'react-canvas-confetti';

  Use `import type` for type-only imports in TypeScript to avoid bundling type definitions into your runtime code.

Quickstart

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;