react-confetti-explosion

Install the package using pnpm:

$ pnpm add react-confetti-explosion

Import ConfettiExplosion and render it conditionally to trigger an explosion. Note that the component is appended to the document body via a Portal by default, so you must manage its mounting and unmounting (e.g., via state) to control when the explosion occurs and to ensure it is cleaned up.

import ConfettiExplosion from 'react-confetti-explosion';

function App() {
  const [isExploding, setIsExploding] = React.useState(false);
  return <>{isExploding && <ConfettiExplosion />}</>;
}

Portal and Layering

By default, ConfettiExplosion uses ReactDOM.createPortal() to append itself to the document body. This ensures it layers above page content, but you must remember to unmount the component when the explosion is finished.

Height and Viewport

• The default height is 120vh to ensure particles land past the bottom of the viewport.
• If you use relative strings (like vh or %), the explosion appearance may vary between mobile and desktop screens.
• If height is set too small, particles may visibly land on the floor instead of disappearing off-screen.

Physics Limitations

The library uses estimated CSS animations rather than a full physics engine to remain lightweight. Some combinations of props may not look perfectly realistic.

Use the following prop configurations to achieve different explosion scales:

Large explosion

• force: 0.8
• duration: 3000
• particleCount: 250
• width: 1600

Medium explosion

• force: 0.6
• duration: 2500
• particleCount: 80
• width: 1000

Small explosion

• force: 0.4
• duration: 2200
• particleCount: 30
• width: 400

The ConfettiExplosion component is the primary entry point for triggering confetti effects. It can be imported as a named export or as the default export from react-confetti-explosion.

import ConfettiExplosion from 'react-confetti-explosion';

// Or as a named export
// import { ConfettiExplosion } from 'react-confetti-explosion';

function MyComponent() {
  return <ConfettiExplosion />;
}