typegpu-confetti

The recommended way to trigger confetti is using the useConfetti hook. This approach requires wrapping a high-level component (ideally at the top of your app) with the ConfettiProvider to ensure the animation covers the screen and the hook is accessible throughout the component tree.

Steps:

1. Wrap your app with ConfettiProvider.
2. Call useConfetti() in a descendant component.
3. Use the returned ref to control the animation via imperative methods.

Available methods on the ref:

• pause(): Pauses the animation.
• resume(): Resumes the animation.
• restart(): Restarts the animation.
• addParticles(amount: number): Adds a specific number of particles to the current simulation. Calling this resets the maxDurationTime counter to zero.

import { ConfettiProvider, useConfetti } from 'typegpu-confetti/react-native';

// 1. Wrap your top-level component
function App() {
  return (
    <ConfettiProvider>
      <SomeInnerComponent />
    </ConfettiProvider>
  );
}

// 2. Use the hook in a descendant
function SomeInnerComponent() {
  const confettiRef = useConfetti();

  return (
    <Button title="run confetti" onPress={() => confettiRef?.current?.addParticles(50)} />
  );
}

If you do not want to use the hook/provider pattern, you can use the Confetti component directly.

Behavior:

• The component is positioned absolutely and covers its closest parent with position: 'relative' (which is the default in React Native).
• You can control it imperatively using a ref of type ConfettiRef.

Imperative Control Example:

import React, { useRef } from 'react';
import { View, Button } from 'react-native';
import type { ConfettiRef } from 'typegpu-confetti';
import { Confetti } from 'typegpu-confetti/react-native';

function SomeComponent() {
  const ref = useRef<ConfettiRef>(null);

  return (
    <View style={{ flex: 1 }}>
      <Confetti 
        initParticleAmount={200} 
        maxParticleAmount={1000} 
        ref={ref} 
      />
      <Button 
        title="add particles" 
        onPress={() => ref.current?.addParticles(200)} 
      />
    </View>
  );
}

The test-app uses a Metro configuration designed for a monorepo environment. It ensures that Metro watches the entire monorepo workspace and correctly resolves node_modules from both the local project directory and the monorepo root. It also enables unstable_enablePackageExports to support modern package export patterns.

Key configuration settings:

• watchFolders: Set to the monorepoRoot to ensure all files in the workspace are monitored.
• resolver.nodeModulesPaths: Includes both the local projectRoot/node_modules and the monorepoRoot/node_modules to allow proper dependency resolution across the workspace.
• resolver.unstable_enablePackageExports: Set to true to enable support for the exports field in package.json.

const { getDefaultConfig } = require('expo/metro-config');
const path = require('node:path');

const projectRoot = __dirname;
const monorepoRoot = path.resolve(projectRoot, '../..');

const config = getDefaultConfig(projectRoot);

config.watchFolders = [monorepoRoot];
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(monorepoRoot, 'node_modules'),
];

config.resolver.unstable_enablePackageExports = true;

module.exports = config;

When using typegpu-confetti, you can provide a configuration object of type ConfettiProps. If you do not provide certain properties, the following default values are used:

• maxDurationTime: The maximum duration of the confetti effect in seconds (default: 2).
• initParticleAmount: The number of particles initialized at the start (default: 200).
• maxParticleAmount: The maximum number of particles allowed in the simulation (default: 1000).
• size: The scale factor for particles (default: 1).
• colorPalette: An array of RGBA colors represented as [r, g, b, a] arrays (default: a specific palette of 5 colors).
• gravity: A function returning a 2D vector (d.vec2f) representing gravity direction and strength. The default is d.vec2f(0, -0.3).
• initParticle: A function used to initialize each particle's position and velocity. The default uses randf.sample() to distribute particles across a specific range.

// Example of the shape of the default configuration object
const defaults = {
  maxDurationTime: 2,
  initParticleAmount: 200,
  maxParticleAmount: 1000,
  size: 1,
  colorPalette: [
    [154, 177, 155, 1],
    [67, 129, 193, 1],
    [99, 71, 77, 1],
    [239, 121, 138, 1],
    [255, 166, 48, 1],
  ],
  gravity: () => {
    'use gpu';
    return d.vec2f(0, -0.3);
  },
  initParticle: (i) => {
    'use gpu';
    // ... initialization logic
  },
};

The Confetti component accepts several props to customize the animation. Note: Changing any prop will restart the animation.

Custom GPU Functions: To use gravity or initParticle, you must mark them with the "use gpu" directive so unplugin-typegpu can transpile them.

GravityFn signature:

(args: { pos: d.v2f }) => d.v2f

InitParticleFn signature:

(args: { index: number }) => void

Inside initParticle, you can access _particles (a TgpuArray of ParticleData) and _maxDurationTime via TypeGPU accessors.