# Particle Button

A status button for async actions, with a spinner, a drawn check and a particle burst on success.

Install with

```
npx shadcn@latest add https://kokonutui.com/r/particle-button.json
```

## Installation

Particle Button is a free, open-source React component in the Kokonut UI [Buttons collection](/content/docs/buttons/index.html). Add it with the shadcn CLI, which copies the source into `components/kokonutui/particle-button.tsx`, so the code is yours to change.

Or add it by hand: install its packages, then copy the source from above into `components/kokonutui/particle-button.tsx`.

```
npx shadcn@latest add @kokonutui/particle-button
```

```
npm install class-variance-authority lucide-react motion
```

## Usage

```
import ParticleButton from "@/components/kokonutui/particle-button";

export default function Example() {
  return <ParticleButton />;
}
```

## Props

- `children`: `ReactNode`, Default: "Save changes"
- `onClick`: `(event: MouseEvent<HTMLButtonElement>) => unknown`
  - Return a promise to show the pending state until it settles. A rejected promise shows the error state. A plain click goes straight to success.
- `onSuccess`: `() => void`
  - Called when the action succeeds, alongside the burst.
- `onError`: `(error: unknown) => void`
  - Called with the rejection reason when the action fails.
- `status`: `ParticleButtonStatus`
  - Controlled status. Without it the button tracks `onClick` itself.
- `successDuration`: `number`, Default: `1600`
  - How long (ms) the success state shows before going back to idle.
- `errorDuration`: `number`, Default: `3200`
  - How long (ms) the error state shows. Longer than success, so it can be read.
- `pendingLabel`: `ReactNode`, Default: "Saving"
- `successLabel`: `ReactNode`, Default: "Saved"
- `errorLabel`: `ReactNode`, Default: "Try again"
- `icon`: `ReactNode`
  - Icon rendered after the idle label.
- `particles`: `boolean`, Default: `true`
  - Fire the particle burst on success.

Also takes every prop of `Omit< ComponentProps<"button">, // Motion owns the drag and animation handlers on a motion.button. | "onClick" | "children" | "onDrag" | "onDragStart" | "onDragEnd" | "onAnimationStart" >` and `VariantProps<typeof buttonVariants>`.

### ParticleButtonStatus

```
type ParticleButtonStatus = "idle" | "pending" | "success" | "error";
```

## Dependencies

| Needs                          | Version   | Comes from                     |
|--------------------------------|-----------|--------------------------------|
| `class-variance-authority`     | `^0.7.1` | npm, installed by the CLI      |
| `lucide-react`                  | `^0.556.0` | npm, installed by the CLI      |
| `motion`                        | `^12.23.25` | npm, installed by the CLI      |
| `button`                        |           | shadcn/ui, added by the CLI    |
| `cn` from `lib/utils.ts`       |           | shadcn init                    |
| React                           | `19`     | Your app                       |
| Tailwind CSS                   | `4`      | Your app                       |

No provider, font or global CSS to set up: the file works as soon as it lands.
