react-confetti-burst 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# react-confetti-burst 🎉
+
+A high-performance, zero-dependency React confetti component with directional bursts using the native Canvas API.
+
+[![npm version](https://badge.fury.io/js/react-confetti-burst.svg)](https://badge.fury.io/js/react-confetti-burst)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/react-confetti-burst)](https://bundlephobia.com/package/react-confetti-burst)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🚀 **Zero dependencies** - Pure React + Canvas API
+- 🎯 **Directional bursts** - Up, down, left, right, radial, or custom angles
+- ⚡ **High performance** - Optimized canvas rendering
+- 📦 **Tiny bundle** - Minimal footprint
+- 🔷 **TypeScript first** - Full type safety built-in
+- ♿ **Accessible** - Respects `prefers-reduced-motion`
+
+## Installation
+
+```bash
+npm install react-confetti-burst
+# or
+yarn add react-confetti-burst
+# or
+pnpm add react-confetti-burst
+```
+
+## Quick Start
+
+### The Simplest Way - ConfettiButton
+
+```tsx
+import { ConfettiButton } from 'react-confetti-burst';
+
+function App() {
+  return (
+    <ConfettiButton>
+      Click me! 🎉
+    </ConfettiButton>
+  );
+}
+```
+
+### Using the Hook - useConfetti
+
+```tsx
+import { useConfetti } from 'react-confetti-burst';
+
+function App() {
+  const { fire } = useConfetti();
+
+  return (
+    <button onClick={(e) => fire({ x: e.clientX, y: e.clientY })}>
+      Celebrate!
+    </button>
+  );
+}
+```
+
+### Functional API - confetti()
+
+```tsx
+import { confetti } from 'react-confetti-burst';
+
+// Basic burst from center
+confetti();
+
+// With options
+confetti({
+  particleCount: 100,
+  spread: 70,
+  origin: { x: 0.5, y: 0.5 }
+});
+```
+
+## API Reference
+
+### Components
+
+#### `<ConfettiButton>`
+
+A button that automatically fires confetti on click.
+
+```tsx
+import { ConfettiButton } from 'react-confetti-burst';
+
+<ConfettiButton
+  confettiOptions={{
+    particleCount: 50,
+    spread: 60,
+    colors: ['#ff6b6b', '#4ecdc4', '#ffe66d'],
+  }}
+>
+  Click me!
+</ConfettiButton>
+```
+
+**Props:**
+- `confettiOptions?: ConfettiBurstOptions` - Configuration for the confetti burst
+- `fireOnClick?: boolean` - Whether to fire on click (default: `true`)
+- All standard button HTML attributes
+
+#### `<ConfettiBurst>`
+
+Declarative component for conditional confetti.
+
+```tsx
+import { ConfettiBurst } from 'react-confetti-burst';
+
+<ConfettiBurst
+  active={showConfetti}
+  origin={{ x: 500, y: 300 }}
+  options={{ particleCount: 50 }}
+  onComplete={() => setShowConfetti(false)}
+/>
+```
+
+### Hooks
+
+#### `useConfetti()`
+
+The main hook for programmatic confetti control.
+
+```tsx
+import { useConfetti } from 'react-confetti-burst';
+
+function App() {
+  const { fire, fireFromElement, isActive, stopAll } = useConfetti();
+
+  // Fire from a specific point
+  const handleClick = (e: React.MouseEvent) => {
+    fire({ x: e.clientX, y: e.clientY }, {
+      particleCount: 50,
+      direction: { direction: 'up', spread: 45 },
+    });
+  };
+
+  // Fire from an element's center
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const handleButtonClick = () => {
+    fireFromElement(buttonRef.current);
+  };
+
+  return (
+    <>
+      <div onClick={handleClick}>Click anywhere</div>
+      <button ref={buttonRef} onClick={handleButtonClick}>
+        Fire from me!
+      </button>
+      {isActive && <p>Animation running...</p>}
+      <button onClick={stopAll}>Stop All</button>
+    </>
+  );
+}
+```
+
+**Returns:**
+- `fire(origin, options?)` - Fire confetti from a point `{ x, y }`
+- `fireFromElement(element, options?)` - Fire from an element's center
+- `isActive` - Boolean indicating if any animation is running
+- `stopAll()` - Stop all active animations
+
+### Functional API
+
+#### `confetti(options?)`
+
+Fire confetti imperatively from anywhere in your code.
+
+```tsx
+import { confetti } from 'react-confetti-burst';
+
+// Simple burst
+confetti();
+
+// Customized burst
+confetti({
+  particleCount: 100,
+  spread: 70,
+  origin: { x: 0.5, y: 0.5 },
+  colors: ['#ff0000', '#00ff00', '#0000ff'],
+});
+
+// Directional burst
+confetti({
+  particleCount: 50,
+  direction: {
+    direction: 'up',
+    spread: 45,
+    velocity: [20, 40],
+  },
+});
+```
+
+## Configuration Options
+
+```typescript
+interface ConfettiBurstOptions {
+  // Number of particles (default: 50)
+  particleCount?: number;
+
+  // Direction configuration
+  direction?: {
+    direction?: 'up' | 'down' | 'left' | 'right' | 'radial' | 'custom';
+    angle?: number;      // For 'custom' direction (degrees)
+    spread?: number;     // Spread angle (default: 45)
+    velocity?: [number, number]; // Min/max velocity
+  };
+
+  // Particle appearance
+  particle?: {
+    size?: [number, number];     // Min/max size
+    colors?: string[];           // Array of colors
+    shapes?: ('square' | 'circle' | 'star' | 'triangle')[];
+    opacity?: [number, number];  // Min/max opacity
+  };
+
+  // Physics
+  physics?: {
+    gravity?: number;      // Gravity strength (default: 0.5)
+    friction?: number;     // Air friction (default: 0.99)
+    wind?: number;         // Horizontal wind force
+  };
+
+  // Lifecycle callbacks
+  onStart?: () => void;
+  onComplete?: () => void;
+}
+```
+
+## Examples
+
+### Directional Bursts
+
+```tsx
+import { useConfetti } from 'react-confetti-burst';
+
+function DirectionalExample() {
+  const { fire } = useConfetti();
+
+  const fireUp = () => fire({ x: 400, y: 500 }, {
+    direction: { direction: 'up', spread: 30 },
+  });
+
+  const fireRadial = () => fire({ x: 400, y: 300 }, {
+    direction: { direction: 'radial' },
+  });
+
+  return (
+    <>
+      <button onClick={fireUp}>Fire Up ⬆️</button>
+      <button onClick={fireRadial}>Radial Burst 💥</button>
+    </>
+  );
+}
+```
+
+### Custom Colors
+
+```tsx
+<ConfettiButton
+  confettiOptions={{
+    particle: {
+      colors: ['#FFD700', '#FF6B6B', '#4ECDC4', '#45B7D1'],
+    },
+  }}
+>
+  Golden Burst ✨
+</ConfettiButton>
+```
+
+### Form Submission Success
+
+```tsx
+import { confetti } from 'react-confetti-burst';
+
+async function handleSubmit(data: FormData) {
+  const response = await submitForm(data);
+  
+  if (response.success) {
+    confetti({
+      particleCount: 100,
+      spread: 70,
+      origin: { x: 0.5, y: 0.6 },
+    });
+  }
+}
+```
+
+## Browser Support
+
+- Chrome 60+
+- Firefox 55+
+- Safari 11+
+- Edge 79+
+
+## License
+
+MIT © [Your Name]
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting a PR.

package/dist/cjs/components.d.ts

@@ -0,0 +1,219 @@
+/**
+ * React components for confetti animations
+ *
+ * Provides declarative components for easy integration of confetti
+ * effects into React applications.
+ */
+import React from 'react';
+import type { ConfettiBurstProps, ConfettiButtonProps, ExplosionHandle, BurstOrigin } from './types';
+/**
+ * Declarative confetti component that fires when active prop changes
+ *
+ * @example
+ * ```tsx
+ * const [celebrate, setCelebrate] = useState(false);
+ *
+ * return (
+ *   <>
+ *     <ConfettiBurst
+ *       active={celebrate}
+ *       origin={{ x: 500, y: 300 }}
+ *       onComplete={() => setCelebrate(false)}
+ *     />
+ *     <button onClick={() => setCelebrate(true)}>
+ *       Celebrate!
+ *     </button>
+ *   </>
+ * );
+ * ```
+ */
+export declare function ConfettiBurst({ active, origin, triggerRef, options, onComplete, }: ConfettiBurstProps): null;
+/**
+ * Handle type for ConfettiTrigger ref
+ */
+export interface ConfettiTriggerHandle {
+    fire: () => ExplosionHandle | null;
+}
+/**
+ * Invisible trigger component that fires confetti from its position
+ *
+ * @example
+ * ```tsx
+ * const triggerRef = useRef<ConfettiTriggerHandle>(null);
+ *
+ * return (
+ *   <div style={{ position: 'relative' }}>
+ *     <ConfettiTrigger ref={triggerRef} options={{ particleCount: 100 }} />
+ *     <button onClick={() => triggerRef.current?.fire()}>
+ *       Fire!
+ *     </button>
+ *   </div>
+ * );
+ * ```
+ */
+export declare const ConfettiTrigger: React.ForwardRefExoticComponent<{
+    options?: ConfettiBurstProps["options"];
+    style?: React.CSSProperties;
+} & React.RefAttributes<ConfettiTriggerHandle>>;
+/**
+ * Button component that automatically fires confetti on click
+ *
+ * @example
+ * ```tsx
+ * <ConfettiButton
+ *   confettiOptions={{
+ *     particleCount: 30,
+ *     direction: { direction: 'up' }
+ *   }}
+ * >
+ *   Submit
+ * </ConfettiButton>
+ * ```
+ */
+export declare const ConfettiButton: React.ForwardRefExoticComponent<ConfettiButtonProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * Props for ConfettiOnMount component
+ */
+interface ConfettiOnMountProps {
+    origin?: BurstOrigin;
+    options?: ConfettiBurstProps['options'];
+    onComplete?: () => void;
+    delay?: number;
+}
+/**
+ * Component that fires confetti when mounted
+ *
+ * @example
+ * ```tsx
+ * // Fire confetti when a success page loads
+ * function SuccessPage() {
+ *   return (
+ *     <div>
+ *       <ConfettiOnMount
+ *         origin={{ x: window.innerWidth / 2, y: window.innerHeight / 3 }}
+ *         options={{ particleCount: 100 }}
+ *       />
+ *       <h1>Success!</h1>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function ConfettiOnMount({ origin, options, onComplete, delay, }: ConfettiOnMountProps): null;
+/**
+ * Props for ConfettiCannon component
+ */
+interface ConfettiCannonProps {
+    /** Position from left (percentage or pixels) */
+    left?: number | string;
+    /** Position from top (percentage or pixels) */
+    top?: number | string;
+    /** Angle in degrees (0 = right, 90 = up) */
+    angle?: number;
+    /** Confetti options */
+    options?: ConfettiBurstProps['options'];
+    /** When true, fires the cannon */
+    fire?: boolean;
+    /** Callback when animation completes */
+    onComplete?: () => void;
+}
+/**
+ * Positioned cannon component for directional confetti bursts
+ *
+ * @example
+ * ```tsx
+ * <ConfettiCannon
+ *   left="10%"
+ *   top="80%"
+ *   angle={60}
+ *   fire={shouldFire}
+ *   options={{ particleCount: 50 }}
+ * />
+ * ```
+ */
+export declare function ConfettiCannon({ left, top, angle, options, fire: shouldFire, onComplete, }: ConfettiCannonProps): null;
+/**
+ * React-confetti compatible Confetti component
+ *
+ * This component provides a drop-in replacement for react-confetti
+ * with continuous confetti that falls from the top of the screen.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - continuous confetti
+ * <Confetti />
+ *
+ * // With options
+ * <Confetti
+ *   width={window.innerWidth}
+ *   height={window.innerHeight}
+ *   numberOfPieces={200}
+ *   recycle={true}
+ *   run={true}
+ * />
+ *
+ * // With custom draw function
+ * <Confetti
+ *   drawShape={ctx => {
+ *     ctx.beginPath();
+ *     ctx.arc(0, 0, 5, 0, Math.PI * 2);
+ *     ctx.fill();
+ *   }}
+ * />
+ * ```
+ */
+export interface ConfettiComponentProps {
+    /** Width of the canvas in pixels (default: window.innerWidth) */
+    width?: number;
+    /** Height of the canvas in pixels (default: window.innerHeight) */
+    height?: number;
+    /** Number of confetti pieces (default: 200) */
+    numberOfPieces?: number;
+    /** Spawn area for confetti pieces */
+    confettiSource?: {
+        x: number;
+        y: number;
+        w?: number;
+        h?: number;
+    };
+    /** Initial horizontal velocity range (default: [4, 10]) */
+    initialVelocityX?: number | {
+        min: number;
+        max: number;
+    };
+    /** Initial vertical velocity range (default: [10, 30]) */
+    initialVelocityY?: number | {
+        min: number;
+        max: number;
+    };
+    /** Whether to recycle confetti (default: true) */
+    recycle?: boolean;
+    /** Whether the animation is running (default: true) */
+    run?: boolean;
+    /** Gravity value (default: 0.3) */
+    gravity?: number;
+    /** Wind value (default: 0) */
+    wind?: number;
+    /** Opacity of confetti pieces (0-1, default: 1) */
+    opacity?: number;
+    /** Custom draw function */
+    drawShape?: (ctx: CanvasRenderingContext2D) => void;
+    /** Tween duration when recycle changes (ms) */
+    tweenDuration?: number;
+    /** Array of colors */
+    colors?: string[];
+    /** Callback when confetti is created */
+    onConfettiComplete?: (confetti: any) => void;
+    /** Frame rate limit */
+    frameRate?: number;
+    /** Z-index of the canvas */
+    style?: React.CSSProperties;
+    /** Class name for the canvas */
+    className?: string;
+}
+export declare function Confetti({ width, height, numberOfPieces, confettiSource, initialVelocityX, initialVelocityY, recycle, run, gravity, wind, opacity, drawShape, tweenDuration, colors, onConfettiComplete, frameRate, }: ConfettiComponentProps): null;
+export declare namespace Confetti {
+    var displayName: string;
+}
+export {};
+//# sourceMappingURL=components.d.ts.map

package/dist/cjs/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/components.tsx"],"names":[],"mappings":"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"}