# Confetti

> A celebration burst: paper pieces launch from a point or rain from the top on closed-form physics (air drag, gravity, sway), spinning and turning over as they fall; one burst per trigger, a static sparkle under reduced motion.

- Type: Component (feedback)
- Access: Free, open source (MIT)
- Page: https://goodui.dev/native/components/confetti
- Markdown: https://goodui.dev/native/components/confetti.md
- Registry item: https://goodui.dev/native/r/confetti.json
- Dependencies: react-native-reanimated, react-native-svg
- Keywords: react native confetti, celebration animation, confetti cannon, success celebration, reanimated confetti, party burst, expo confetti

## When to use

- A real milestone the person worked for: a goal reached, a first sale, a streak, a course finished.
- The end of a flow worth celebrating, together with a clear confirmation (success-check or the screen's own result).

## When not to use

- Routine confirmations such as saving a form: let the button show success.
- As the only confirmation of an action: pair it with a visible result.
- A loading or progress indicator: use progress-ring or the button's own pending state.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add https://goodui.dev/native/r/confetti.json
npx expo install --fix
```

The component lands in `components/goodui-native/confetti/` and imports the foundation from `components/goodui-native/foundation/` with relative paths.

## Usage

```tsx
import { useState } from "react";
import { View } from "react-native";
import { Button } from "@/components/goodui-native/button/button";
import { Confetti } from "@/components/goodui-native/confetti/confetti";

export function GoalReached() {
  const [celebrations, setCelebrations] = useState(0);
  return (
    <View>
      <Button onPress={() => setCelebrations((c) => c + 1)}>Log 10,000 steps</Button>
      <Confetti trigger={celebrations} announcement="Goal reached" />
    </View>
  );
}
```

## Examples

### Burst out of a button through a ref

```tsx
const buttonRef = useRef<View>(null);
const confetti = useRef<ConfettiHandle>(null);

<View ref={buttonRef} collapsable={false}>
  <Button onPress={() => confetti.current?.fire()}>Claim reward</Button>
</View>
<Confetti ref={confetti} origin={buttonRef} count={36} />
```

### Inside a card instead of the whole screen

```tsx
<View style={{ overflow: "hidden" }}>
  {card}
  <Confetti trigger={done} fullScreen={false} origin="center" power={0.6} />
</View>
```

## API reference

### Confetti

`import { Confetti } from "@/components/goodui-native/confetti/confetti";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` | `number \| string \| boolean \| null` | – | Fires one burst every time this changes to a new truthy value after mount (a counter, a timestamp, `true`). |
| `ref` | `Ref<ConfettiHandle>` | – | Imperative handle: `ref.current?.fire()`. |
| `origin` | `ConfettiOrigin` | `"top"` | `top` rains across the width; a point or an element ref bursts upward from there. Default `top`. |
| `count` | `number` | `44` | Pieces per burst, 8 to 120. Default 44: enough to read as a celebration, light enough for low-end phones. |
| `spread` | `number` | `55` | Half-angle of a point burst in degrees, around straight up. Default 55. |
| `power` | `number` | `1` | Launch speed multiplier for point bursts. Default 1. |
| `colors` | `string[]` | – | Piece colors. Defaults to the theme accent and status colors. |
| `duration` | `number` | `2400` | Milliseconds a burst lives. Default 2400. |
| `fullScreen` | `boolean` | `true` | Render above everything through the portal (default), or inside the nearest positioned parent. |
| `haptic` | `HapticName \| false` | `"celebrate"` | Cue as a burst fires. `false` turns it off. Default `celebrate`. |
| `announcement` | `string` | – | Read by screen readers when a burst fires, for example "Goal reached". The pieces themselves are hidden. |
| `onComplete` | `() => void` | – | Called when a burst has finished. |

## Accessibility

- The pieces are hidden from screen readers and never take touches (pointerEvents none).
- Pass `announcement` to have a burst read out, for example 'Goal reached'.

## Motion

- Point bursts launch in a cone around straight up (spread), denser in the middle; 'top' rains pieces across the width with staggered starts.
- Every piece follows a closed-form path with linear air drag and gravity plus a growing sideways sway, spins, and turns over (scaleY follows a cosine) like paper; it fades in the last 28 % of its life.
- Up to three bursts overlap; a fourth replaces the oldest.
- Reduced motion: no pieces travel. Seven four-point sparkles at the origin fade in, hold and fade out (about 1.1 s).

## Haptics

- celebrate as each burst fires (haptic prop; false turns it off). Never repeated during the burst.

## Performance

- One linear clock per burst on the UI thread; each piece is a plain Animated.View whose style is computed from that clock, no per-frame React state.
- Default 44 pieces; count is clamped to 8 to 120. Keep it under about 60 for low-end Android.
- Nothing is mounted between bursts.

## Notes for AI

- trigger fires on every change to a new truthy value after mount (a counter works best); it does not fire on the first render.
- For a burst from an element pass a ref to a View with collapsable={false} as origin; it is measured when the burst fires.
- fullScreen (default) renders through the ThemeProvider portal above everything. With fullScreen={false} it fills the nearest parent; give that parent overflow hidden.
- Default colors are the accent and status colors from the theme; pass colors to use your own tokens.

## Related

- [Success check](https://goodui.dev/native/components/success-check.md): A success or error moment: the circle springs in, the check draws itself while a ring pulses out and the title rises in; the error variant draws a cross and shakes once. Inline or fullscreen, optionally with confetti.
- [Like button](https://goodui.dev/native/components/like-button.md): A like toggle with one moment of delight: the heart squashes and springs back filled, a ring expands and particles burst while the count rolls; it updates optimistically and rolls back if the request fails.
- [Progress ring](https://goodui.dev/native/components/progress-ring.md): A circular progress ring that fills on a spring, laps itself past 100 % with a gap that lifts the lap off the ring, and bounces once with a success haptic when it completes.

## Guidance for AI tools

Confetti: A celebration burst: paper pieces launch from a point or rain from the top on closed-form physics (air drag, gravity, sway), spinning and turning over as they fall; one burst per trigger, a static sparkle under reduced motion. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt