Particle Button - React Component | Kokonut UI
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. 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
onClickitself.
- Controlled status. Without it the button tracks
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.