# Celebrate button

> A button that bursts confetti from its own edges on success while the label morphs to done.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/celebrate-button
- Markdown: https://uiarc.dev/components/celebrate-button/markdown
- Source file: `registry/components/celebrate-button/celebrate-button.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, action, canvas, new, confetti button, celebrate button, success animation, particle burst, success button, react confetti, done button

## When to use

- Completing a milestone: publish, launch, finish setup, send the first invoice.
- Onboarding steps where a small reward encourages the next one.
- Marketing demos where the moment of success is the story.

## When not to use

- Use button with a loading state for routine saves and form submits.
- Use hold-to-confirm for destructive actions.
- Avoid it in dense toolbars and tables.

## Installation

Celebrate button is part of Arc Pro. The live preview is public; the source and install command need Pro.

### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/celebrate-button
```

### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

## Usage

```tsx
import { CelebrateButton } from "@/components/arc/celebrate-button/celebrate-button";

export function PublishAction() {
  return (
    <CelebrateButton onAction={() => publishSite()} pendingLabel="Publishing" successLabel="Published">
      Publish site
    </CelebrateButton>
  );
}
```

## API reference

### CelebrateButton

A button that bursts confetti from its own edges when its action succeeds, while the label morphs to a done state and the width springs to fit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | The resting label. |
| `onAction` | `() => void \| Promise<unknown>` | – | Runs on press. A promise shows the pending state; a rejection shows the error label without a burst. |
| `status` | `"idle" \| "pending" \| "success" \| "error"` | – | Controlled status. Moving to success plays the burst. |
| `onStatusChange` | `(status: CelebrateStatus) => void` | – | Called on every status change, including the reset to idle. |
| `successLabel` | `ReactNode` | `"Done"` | Label after success, shown with a check. |
| `pendingLabel` | `ReactNode` | – | Label while the action runs, shown with a spinner. Defaults to the resting label. |
| `errorLabel` | `ReactNode` | `"Try again"` | Label after a failure. |
| `resetAfter` | `number` | `2400` | Milliseconds before returning to rest. 0 stays done. |
| `cooldown` | `number` | `1200` | Shortest time in ms between two bursts. |
| `colors` | `string[]` | – | Confetti colours. Defaults to the accent in three tones, a sunny yellow, and a little ink, resolved from the theme at burst time. |
| `particles` | `number` | `44` | Pieces per burst. |
| `className` | `string` | – | Extra class on the wrapper. |
| `...rest` | `ButtonHTMLAttributes` | – | Other button attributes, such as disabled, name, or aria attributes. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Runs the action. Presses during pending or done are ignored. |

## Accessibility

- It is a native button; aria-busy is set while pending.
- A polite live region announces the success or error label.
- The confetti canvas is aria-hidden and ignores the pointer.
- Success is shown by a check and a label, never by colour or confetti alone.

## Motion

- Confetti leaves from points on the button's rounded outline, moving outward and up, then falls under light gravity with air drag and a sideways flutter.
- Ribbons and squares tumble by squashing one axis with the flip angle; circles stay round; every piece fades before it lands.
- The button kicks to 1.07 as the burst leaves, the label rises out of a blur, and the width springs to the new label.
- Bursts are rate limited by cooldown and capped at 180 live pieces.
- Reduced motion skips the particles and kick and crossfades the label to the check.
- The button fills with the accent, and the confetti is mostly the accent in three tones with a supporting yellow and a little ink, so it follows the accent and theme settings.

## Responsive behavior

- The confetti canvas reaches 150px beside and 190px above the button; leave room or let it overflow the container.
- Touch presses get the same press scale and burst as a mouse.

## Performance

- Particles run on one canvas that only exists during a burst and stops when the last piece fades.
- The canvas is capped at 2x device pixel ratio.

## Notes for AI

- Save it for moments worth celebrating: publishing, finishing onboarding, a first payment. Everyday saves should use a plain button.
- Return the real promise from onAction so the pending and error states are honest.
- Use the controlled status when the action is triggered elsewhere, such as a form submit.
- Keep one celebrate button per view so the burst stays special.

## Related

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Action morph](https://uiarc.dev/components/action-morph/markdown): A floating button that morphs into a quick-action menu, then an inline form, then back with a check.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.

## Also in loaders

- [Stretch refresh](https://uiarc.dev/components/stretch-refresh/markdown): Pull a feed down and a line stretches to tell you when to let go.
- [Feedback morph](https://uiarc.dev/components/feedback-morph/markdown): A feedback button that becomes a form, then a thank-you, in one shape.
- [Morph loader](https://uiarc.dev/components/morph-loader/markdown): Tiny loaders that morph between shapes and fold into a check or a cross when done.
- [Skeleton morph](https://uiarc.dev/components/skeleton-morph/markdown): Loading skeletons that grow into the real content, block by block, instead of swapping.
- [Black hole](https://uiarc.dev/components/black-hole/markdown): A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out.
- [Slide to confirm](https://uiarc.dev/components/slide-to-confirm/markdown): A slide-to-confirm control. The thumb pulls a liquid fill behind it and makes the track swell. It snaps back on a spring if released early. Past the threshold, the track draws into the thumb and the chevron morphs into a success check, with pending and error states.
- [Charge session](https://uiarc.dev/components/charge-session/markdown): An EV or device charging card. Energy packets flow from a charger along the cable into the battery pack, which fills toward a draggable charge limit. The charge curve tapers near full, and power, energy, time to limit and cost update live. Stop charging drains the flow.

## Guidance for AI tools

Celebrate button: A button that bursts confetti from its own edges on success while the label morphs to done. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt
