react-confetti-burst 1.0.5 → 1.0.7

package/dist/types/index.d.ts

@@ -115,10 +115,26 @@ export interface TextShape {
 	/** Cached bitmap for performance */
 	readonly _bitmap?: ImageBitmap | HTMLCanvasElement;
 }
+/**
+ * Custom shape created from an image (URL or HTMLImageElement)
+ */
+export interface ImageShape {
+	readonly type: "image";
+	/** Image source URL */
+	readonly src: string;
+	/** Pre-loaded image element */
+	readonly image?: HTMLImageElement;
+	/** Scale factor. Default: 1 */
+	readonly scalar?: number;
+	/** Display width */
+	readonly width?: number;
+	/** Display height */
+	readonly height?: number;
+}
 /**
  * Custom shape union type
  */
-export type CustomShape = PathShape | TextShape;
+export type CustomShape = PathShape | TextShape | ImageShape;
 /**
  * Shape types for confetti particles
  */
@@ -392,7 +408,7 @@ export interface CanvasConfig {
 	readonly height: number | null;
 	/** Auto-resize on window resize. Default: true */
 	readonly autoResize: boolean;
-	/** Resize debounce delay (ms). Default: 100 */
+	/** @deprecated Currently unused. Resize events are handled immediately via ResizeObserver. */
 	readonly resizeDebounce: number;
 	/** Frame rate cap (null = uncapped/60fps). Default: null */
 	readonly frameRate: number | null;
@@ -709,6 +725,110 @@ export interface ConfettiButtonProps extends React$1.ButtonHTMLAttributes<HTMLBu
 	readonly fireOnClick?: boolean;
 	/** Children elements */
 	readonly children: React$1.ReactNode;
+	/** Offset the burst origin from the button center (in pixels) */
+	readonly originOffset?: {
+		x?: number;
+		y?: number;
+	};
+	/** Shorthand direction for the burst (e.g., 'up', 'down') */
+	readonly direction?: BurstDirection;
+}
+/**
+ * Props for the Confetti component (react-confetti compatible API)
+ */
+export interface ConfettiProps {
+	/** Canvas width */
+	readonly width?: number;
+	/** Canvas height */
+	readonly height?: number;
+	/** Number of confetti pieces at one time */
+	readonly numberOfPieces?: number;
+	/** Rectangle where confetti should spawn */
+	readonly confettiSource?: SpawnArea;
+	/** Friction coefficient */
+	readonly friction?: number;
+	/** Wind force */
+	readonly wind?: number;
+	/** Gravity strength */
+	readonly gravity?: number;
+	/** Initial horizontal velocity */
+	readonly initialVelocityX?: number | {
+		min: number;
+		max: number;
+	};
+	/** Initial vertical velocity */
+	readonly initialVelocityY?: number | {
+		min: number;
+		max: number;
+	};
+	/** Colors array */
+	readonly colors?: string[];
+	/** Opacity */
+	readonly opacity?: number;
+	/** Keep spawning confetti */
+	readonly recycle?: boolean;
+	/** Run the animation */
+	readonly run?: boolean;
+	/** Frame rate cap */
+	readonly frameRate?: number;
+	/** Tween duration */
+	readonly tweenDuration?: number;
+	/** Tween function */
+	readonly tweenFunction?: EasingFunction;
+	/** Custom draw function */
+	readonly drawShape?: (ctx: CanvasRenderingContext2D) => void;
+	/** Callback when all confetti has fallen */
+	readonly onConfettiComplete?: () => void;
+	/** Canvas ref */
+	readonly canvasRef?: React$1.RefObject<HTMLCanvasElement>;
+	/** Canvas class name */
+	readonly className?: string;
+	/** Canvas style */
+	readonly style?: React$1.CSSProperties;
+}
+/**
+ * Preset configuration names
+ */
+export type PresetName = "default" | "celebration" | "firework" | "snow" | "rain" | "sparkle" | "confetti" | "emoji" | "hearts" | "stars" | "money" | "pride" | "christmas" | "halloween" | "newYear" | "birthday";
+/**
+ * Preset configuration
+ */
+export interface PresetConfig {
+	readonly name: PresetName;
+	readonly options: ConfettiBurstOptions;
+	readonly description: string;
+}
+/**
+ * Confetti instance created by confetti.create()
+ */
+export interface ConfettiInstance {
+	(options?: CanvasConfettiOptions): Promise<void> | null;
+	reset(): void;
+}
+/**
+ * The confetti function type with all attached convenience methods.
+ * This provides proper TypeScript types for the functional API's
+ * attached methods like confetti.fireworks(), confetti.snow(), etc.
+ */
+export interface ConfettiFunction {
+	(options?: CanvasConfettiOptions): Promise<void> | null;
+	create(canvas: HTMLCanvasElement, options?: ConfettiCreateOptions): ConfettiInstance;
+	reset(): void;
+	fireworks(options?: Partial<CanvasConfettiOptions>): Promise<void>;
+	schoolPride(options?: Partial<CanvasConfettiOptions>): {
+		cancel: () => void;
+	};
+	snow(options?: {
+		duration?: number;
+	} & Partial<CanvasConfettiOptions>): {
+		cancel: () => void;
+	};
+	burst(origin: {
+		x: number;
+		y: number;
+	}, options?: Partial<CanvasConfettiOptions>): Promise<void> | null;
+	destroyAll(): void;
+	getShapes(): string[];
 }
 /**
  * Default vibrant color palette for confetti particles
@@ -730,6 +850,34 @@ export declare const DEFAULT_DIRECTION: DirectionConfig;
  * Optimized for realistic confetti appearance
  */
 export declare const DEFAULT_PARTICLE: ParticleConfig;
+/**
+ * Default trail configuration
+ */
+export declare const DEFAULT_TRAIL: TrailConfig;
+/**
+ * Default glow configuration
+ */
+export declare const DEFAULT_GLOW: GlowConfig;
+/**
+ * Default continuous mode configuration
+ */
+export declare const DEFAULT_CONTINUOUS: ContinuousConfig;
+/**
+ * Default firework configuration
+ */
+export declare const DEFAULT_FIREWORK: FireworkConfig;
+/**
+ * Default canvas configuration
+ */
+export declare const DEFAULT_CANVAS: CanvasConfig;
+/**
+ * Default accessibility configuration
+ */
+export declare const DEFAULT_ACCESSIBILITY: {
+	readonly disableForReducedMotion: false;
+	readonly ariaLabel: "Confetti animation";
+	readonly ariaHidden: true;
+};
 /**
  * Complete default configuration
  */
@@ -742,6 +890,16 @@ export declare const DIRECTION_ANGLES: Record<Exclude<BurstDirection, "custom" |
  * Easing functions for smooth animations
  */
 export declare const EASING_FUNCTIONS: Record<EasingPreset, EasingFunction>;
+/**
+ * Sets the maximum particle pool size.
+ * Call before creating any ConfettiEngine instances.
+ * @param size - Maximum number of particles to pool (default: 500)
+ */
+export declare function setMaxPoolSize(size: number): void;
+/**
+ * Gets the current maximum particle pool size.
+ */
+export declare function getMaxPoolSize(): number;
 /**
  * Main confetti engine class
  */
@@ -861,6 +1019,77 @@ export declare function forceCleanup(): void;
  * ```
  */
 export declare function useConfetti(): UseConfettiReturn;
+/**
+ * Hook for confetti triggered by a ref element
+ *
+ * @param options - Confetti configuration options
+ * @returns Ref to attach to trigger element and fire function
+ *
+ * @example
+ * ```tsx
+ * const { ref, fire } = useConfettiTrigger();
+ *
+ * return (
+ *   <button ref={ref} onClick={fire}>
+ *     Celebrate!
+ *   </button>
+ * );
+ * ```
+ */
+export declare function useConfettiTrigger<T extends HTMLElement = HTMLElement>(options?: ConfettiBurstOptions): {
+	ref: React$1.RefObject<T>;
+	fire: () => ExplosionHandle | null;
+	isActive: boolean;
+};
+/**
+ * Hook for auto-firing confetti when a condition becomes true
+ *
+ * @param condition - When true, fires confetti
+ * @param origin - Origin point for the burst
+ * @param options - Confetti configuration options
+ *
+ * @example
+ * ```tsx
+ * const [isComplete, setIsComplete] = useState(false);
+ *
+ * useConfettiOnCondition(isComplete, { x: 500, y: 300 });
+ * ```
+ */
+export declare function useConfettiOnCondition(condition: boolean, origin: BurstOrigin, options?: ConfettiBurstOptions): void;
+/**
+ * Hook for sequencing multiple confetti bursts
+ *
+ * @param bursts - Array of burst configurations with delays
+ * @returns Start function and active state
+ *
+ * @example
+ * ```tsx
+ * const { start, isActive } = useConfettiSequence([
+ *   { origin: { x: 100, y: 100 }, delay: 0 },
+ *   { origin: { x: 300, y: 100 }, delay: 200 },
+ *   { origin: { x: 500, y: 100 }, delay: 400 },
+ * ]);
+ * ```
+ */
+export declare function useConfettiSequence(bursts: Array<{
+	origin: BurstOrigin;
+	options?: ConfettiBurstOptions;
+	delay: number;
+}>): {
+	start: () => void;
+	isActive: boolean;
+	cancel: () => void;
+};
+/**
+ * Hook for viewport-centered confetti
+ *
+ * @param options - Confetti configuration options
+ * @returns Fire function for center-screen confetti
+ */
+export declare function useConfettiCenter(options?: ConfettiBurstOptions): {
+	fire: () => ExplosionHandle;
+	isActive: boolean;
+};
 /**
  * Declarative confetti component that fires when active prop changes
  *
@@ -883,6 +1112,33 @@ export declare function useConfetti(): UseConfettiReturn;
  * ```
  */
 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$1.ForwardRefExoticComponent<{
+	options?: ConfettiBurstProps["options"];
+	style?: React$1.CSSProperties;
+} & React$1.RefAttributes<ConfettiTriggerHandle>>;
 /**
  * Button component that automatically fires confetti on click
  *
@@ -900,11 +1156,163 @@ export declare function ConfettiBurst({ active, origin, triggerRef, options, onC
  */
 export declare const ConfettiButton: React$1.ForwardRefExoticComponent<ConfettiButtonProps & React$1.RefAttributes<HTMLButtonElement>>;
 /**
- * Generates a random number within a range
+ * Props for ConfettiOnMount component
+ */
+export 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
+ */
+export 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$1.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;
+}
+/**
+ * Generates a random number within a range (inclusive min, exclusive max)
+ * @param min - Minimum value (inclusive)
+ * @param max - Maximum value (exclusive)
+ * @returns Random number in [min, max)
+ * @example randomInRange(5, 15) // e.g. 8.342
  */
 export declare function randomInRange(min: number, max: number): number;
 /**
- * Generates a random integer within a range (inclusive)
+ * Generates a random integer within a range (inclusive on both ends)
+ * @param min - Minimum integer value (inclusive)
+ * @param max - Maximum integer value (inclusive)
+ * @returns Random integer in [min, max]
+ * @example randomInt(1, 6) // e.g. 3
  */
 export declare function randomInt(min: number, max: number): number;
 /**
@@ -913,18 +1321,34 @@ export declare function randomInt(min: number, max: number): number;
 export declare function randomFromArray<T>(array: readonly T[]): T;
 /**
  * Clamps a value between min and max
+ * @param value - Value to clamp
+ * @param min - Minimum bound
+ * @param max - Maximum bound
+ * @returns Clamped value in [min, max]
+ * @example clamp(15, 0, 10) // 10
  */
 export declare function clamp(value: number, min: number, max: number): number;
 /**
  * Linear interpolation between two values
+ * @param start - Start value (t=0)
+ * @param end - End value (t=1)
+ * @param t - Interpolation factor, clamped to [0, 1]
+ * @returns Interpolated value
+ * @example lerp(0, 100, 0.5) // 50
  */
 export declare function lerp(start: number, end: number, t: number): number;
 /**
  * Converts degrees to radians
+ * @param degrees - Angle in degrees
+ * @returns Angle in radians
+ * @example degToRad(180) // Math.PI
  */
 export declare function degToRad(degrees: number): number;
 /**
  * Converts radians to degrees
+ * @param radians - Angle in radians
+ * @returns Angle in degrees
+ * @example radToDeg(Math.PI) // 180
  */
 export declare function radToDeg(radians: number): number;
 /**
@@ -985,10 +1409,14 @@ export declare namespace confetti {
 	};
 	var reset: () => void;
 	var fireworks: (options?: Partial<CanvasConfettiOptions>) => Promise<void>;
-	var schoolPride: (options?: Partial<CanvasConfettiOptions>) => void;
+	var schoolPride: (options?: Partial<CanvasConfettiOptions>) => {
+		cancel: () => void;
+	};
 	var snow: (options?: {
 		duration?: number;
-	} & Partial<CanvasConfettiOptions>) => void;
+	} & Partial<CanvasConfettiOptions>) => {
+		cancel: () => void;
+	};
 	var burst: (origin: {
 		x: number;
 		y: number;
@@ -996,6 +1424,300 @@ export declare namespace confetti {
 	var destroyAll: () => void;
 	var getShapes: () => string[];
 }
+/**
+ * Color palettes for presets
+ */
+export declare const COLOR_PALETTES: {
+	readonly rainbow: readonly string[];
+	readonly pride: readonly [
+		"#E40303",
+		"#FF8C00",
+		"#FFED00",
+		"#008026",
+		"#24408E",
+		"#732982"
+	];
+	readonly christmas: readonly [
+		"#C41E3A",
+		"#165B33",
+		"#FFD700",
+		"#FFFFFF",
+		"#BB2528"
+	];
+	readonly halloween: readonly [
+		"#FF6600",
+		"#000000",
+		"#8B008B",
+		"#00FF00",
+		"#FFD700"
+	];
+	readonly pastel: readonly [
+		"#FFB3BA",
+		"#FFDFBA",
+		"#FFFFBA",
+		"#BAFFC9",
+		"#BAE1FF"
+	];
+	readonly neon: readonly [
+		"#FF00FF",
+		"#00FFFF",
+		"#FF0080",
+		"#80FF00",
+		"#FF8000"
+	];
+	readonly gold: readonly [
+		"#FFD700",
+		"#DAA520",
+		"#B8860B",
+		"#FFC125",
+		"#FFDF00"
+	];
+	readonly silver: readonly [
+		"#C0C0C0",
+		"#A8A8A8",
+		"#D3D3D3",
+		"#DCDCDC",
+		"#E8E8E8"
+	];
+	readonly hearts: readonly [
+		"#FF69B4",
+		"#FF1493",
+		"#FF007F",
+		"#DC143C",
+		"#FFB6C1"
+	];
+	readonly ocean: readonly [
+		"#006994",
+		"#00CED1",
+		"#20B2AA",
+		"#48D1CC",
+		"#87CEEB"
+	];
+};
+/**
+ * Emoji sets for presets
+ */
+export declare const EMOJI_SETS: {
+	readonly celebration: readonly [
+		"\uD83C\uDF89",
+		"\uD83C\uDF8A",
+		"\uD83E\uDD73",
+		"\u2728",
+		"\uD83C\uDF88"
+	];
+	readonly hearts: readonly [
+		"\u2764\uFE0F",
+		"\uD83D\uDC95",
+		"\uD83D\uDC96",
+		"\uD83D\uDC97",
+		"\uD83D\uDC93",
+		"\uD83D\uDC98"
+	];
+	readonly stars: readonly [
+		"\u2B50",
+		"\uD83C\uDF1F",
+		"\u2728",
+		"\uD83D\uDCAB",
+		"\u26A1"
+	];
+	readonly money: readonly [
+		"\uD83D\uDCB0",
+		"\uD83D\uDCB5",
+		"\uD83D\uDCB8",
+		"\uD83E\uDD11",
+		"\uD83D\uDC8E"
+	];
+	readonly christmas: readonly [
+		"\uD83C\uDF84",
+		"\uD83C\uDF85",
+		"\uD83C\uDF81",
+		"\u2744\uFE0F",
+		"\u2B50"
+	];
+	readonly halloween: readonly [
+		"\uD83C\uDF83",
+		"\uD83D\uDC7B",
+		"\uD83E\uDD87",
+		"\uD83D\uDD77\uFE0F",
+		"\uD83D\uDC80"
+	];
+	readonly birthday: readonly [
+		"\uD83C\uDF82",
+		"\uD83C\uDF81",
+		"\uD83C\uDF88",
+		"\uD83C\uDF89",
+		"\uD83E\uDD73"
+	];
+	readonly food: readonly [
+		"\uD83C\uDF55",
+		"\uD83C\uDF54",
+		"\uD83C\uDF5F",
+		"\uD83C\uDF2D",
+		"\uD83C\uDF7F"
+	];
+};
+/**
+ * Preset configurations for quick setup
+ */
+export declare const PRESETS: Record<PresetName, PresetConfig>;
+/**
+ * Get a preset configuration by name
+ */
+export declare function getPreset(name: PresetName): PresetConfig;
+/**
+ * Get all available preset names
+ */
+export declare function getPresetNames(): readonly PresetName[];
+/**
+ * Convert a preset's ConfettiBurstOptions to CanvasConfettiOptions
+ * for use with the confetti() functional API.
+ *
+ * Presets use the nested ConfettiBurstOptions format (particle.colors,
+ * physics.gravity, direction.spread), but confetti() expects the flat
+ * CanvasConfettiOptions format (colors, gravity, spread).
+ *
+ * @example
+ * ```ts
+ * import { getPreset, presetToCanvasOptions, confetti } from 'react-confetti-burst';
+ *
+ * const preset = getPreset('celebration');
+ * confetti(presetToCanvasOptions(preset.options));
+ * ```
+ *
+ * @param options - ConfettiBurstOptions from a preset (or any hook/component options)
+ * @returns Equivalent CanvasConfettiOptions for use with confetti()
+ */
+export declare function presetToCanvasOptions(options: ConfettiBurstOptions): CanvasConfettiOptions;
+/**
+ * Options for creating a shape from an SVG path
+ */
+export interface ShapeFromPathOptions {
+	/** SVG path string (d attribute) */
+	readonly path: string;
+	/** Optional 2D transformation matrix [a, b, c, d, e, f] */
+	readonly matrix?: readonly number[];
+	/** Fill color (optional, will use particle color if not set) */
+	readonly fillColor?: string;
+	/** Stroke color (optional) */
+	readonly strokeColor?: string;
+	/** Stroke width (optional) */
+	readonly strokeWidth?: number;
+}
+/**
+ * Options for creating a shape from text/emoji
+ */
+export interface ShapeFromTextOptions {
+	/** Text or emoji to render */
+	readonly text: string;
+	/** Scale factor for the text size. Default: 1 */
+	readonly scalar?: number;
+	/** Text color (optional, will use particle color if not set) */
+	readonly color?: string;
+	/** Font family. Default: 'serif' */
+	readonly fontFamily?: string;
+	/** Font weight. Default: 'normal' */
+	readonly fontWeight?: string | number;
+	/** Font style. Default: 'normal' */
+	readonly fontStyle?: "normal" | "italic" | "oblique";
+}
+/**
+ * Create a custom shape from an SVG path string.
+ *
+ * This is compatible with canvas-confetti's shapeFromPath function.
+ *
+ * @example
+ * ```typescript
+ * // Simple star shape
+ * const star = shapeFromPath({
+ *   path: 'M0,-1 L0.588,0.809 L-0.951,-0.309 L0.951,-0.309 L-0.588,0.809 Z'
+ * });
+ *
+ * // With transformation matrix
+ * const scaledStar = shapeFromPath({
+ *   path: 'M0,-1 L0.588,0.809 L-0.951,-0.309 L0.951,-0.309 L-0.588,0.809 Z',
+ *   matrix: [2, 0, 0, 2, 0, 0] // Scale 2x
+ * });
+ *
+ * // Usage with confetti
+ * fire({ x: 0.5, y: 0.5 }, {
+ *   particle: { shapes: [star, 'circle'] }
+ * });
+ * ```
+ *
+ * @param options - Shape configuration options
+ * @returns PathShape object for use in confetti configuration
+ */
+export declare function shapeFromPath(options: ShapeFromPathOptions): PathShape;
+/**
+ * Create a custom shape from text or an emoji.
+ *
+ * This is compatible with canvas-confetti's shapeFromText function.
+ *
+ * @example
+ * ```typescript
+ * // Emoji confetti
+ * const heart = shapeFromText({ text: '❤️' });
+ * const party = shapeFromText({ text: '🎉', scalar: 2 });
+ *
+ * // Custom text
+ * const yay = shapeFromText({
+ *   text: 'YAY',
+ *   fontFamily: 'Impact',
+ *   color: '#ff0000'
+ * });
+ *
+ * // Usage with confetti
+ * fire({ x: 0.5, y: 0.5 }, {
+ *   particle: { shapes: [heart, party, yay] }
+ * });
+ * ```
+ *
+ * @param options - Text shape configuration options
+ * @returns TextShape object for use in confetti configuration
+ */
+export declare function shapeFromText(options: ShapeFromTextOptions): TextShape;
+/**
+ * Create a bitmap shape from an image URL or HTMLImageElement.
+ *
+ * @example
+ * ```typescript
+ * const logo = await shapeFromImage({
+ *   src: '/logo.png',
+ *   width: 32,
+ *   height: 32
+ * });
+ *
+ * fire({ x: 0.5, y: 0.5 }, {
+ *   particle: { shapes: [logo] }
+ * });
+ * ```
+ *
+ * @param options - Image shape configuration options
+ * @returns Promise resolving to a custom shape
+ */
+export declare function shapeFromImage(options: {
+	readonly src: string | HTMLImageElement;
+	readonly width?: number;
+	readonly height?: number;
+	readonly scalar?: number;
+}): Promise<ImageShape>;
+/**
+ * Create multiple shapes from an array of emoji.
+ *
+ * @example
+ * ```typescript
+ * const partyEmoji = shapesFromEmoji(['🎉', '🎊', '✨', '🥳']);
+ *
+ * fire({ x: 0.5, y: 0.5 }, {
+ *   particle: { shapes: partyEmoji }
+ * });
+ * ```
+ *
+ * @param emojis - Array of emoji strings
+ * @param options - Optional common options for all emoji
+ * @returns Array of TextShape objects
+ */
+export declare function shapesFromEmoji(emojis: readonly string[], options?: Omit<ShapeFromTextOptions, "text">): TextShape[];
 
 export {
 	confetti as default,