"use client"; /** * @author: @dorianbaffier * @description: Particle Button * @version: 2.0.0 * @date: 2026-10-16 * @license: MIT * @website: https://kokonutui.com * @github: https://github.com/kokonut-labs/kokonutui * * A status button for async actions. Return a promise from `onClick` and the * label crossfades to a spinner, then to a drawn check with a burst of * particles, or to an error with a shake. The width follows every label. */ import type { VariantProps } from "class-variance-authority"; import { AlertCircle } from "lucide-react"; import { AnimatePresence, MotionConfig, motion, useAnimationControls, useReducedMotion, } from "motion/react"; import { type ComponentProps, type MouseEvent, type ReactNode, useEffect, useLayoutEffect, useRef, useState, } from "react"; import { buttonVariants } from "@/components/ui/button"; import { cn } from "@/lib/utils"; export type ParticleButtonStatus = "idle" | "pending" | "success" | "error"; export interface ParticleButtonProps extends Omit< ComponentProps<"button">, // Motion owns the drag and animation handlers on a motion.button. | "onClick" | "children" | "onDrag" | "onDragStart" | "onDragEnd" | "onAnimationStart" >, VariantProps { children?: ReactNode; /** * 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. */ onClick?: (event: MouseEvent) => unknown; /** Called when the action succeeds, alongside the burst. */ onSuccess?: () => void; /** Called with the rejection reason when the action fails. */ onError?: (error: unknown) => void; /** Controlled status. Without it the button tracks `onClick` itself. */ status?: ParticleButtonStatus; /** How long (ms) the success state shows before going back to idle. */ successDuration?: number; /** How long (ms) the error state shows. Longer than success, so it can be read. */ errorDuration?: number; pendingLabel?: ReactNode; successLabel?: ReactNode; errorLabel?: ReactNode; /** Icon rendered after the idle label. */ icon?: ReactNode; /** Fire the particle burst on success. */ particles?: boolean; } const EASE_OUT = [0.23, 1, 0.32, 1] as const; const LABEL_TRANSITION = { duration: 0.2, ease: EASE_OUT }; const WIDTH_TRANSITION = { type: "spring", duration: 0.35, bounce: 0 } as const; const SHAKE = { x: [0, -5, 5, -3, 3, 0] }; // --- Particles ------------------------------------------------------------- interface Particle { x: number; y: number; vx: number; vy: number; angle: number; spin: number; w: number; h: number; } const PARTICLE_COUNT = 18; const GRAVITY = 0.0016; // px per ms² const DRAG = 0.0022; // fraction of velocity lost per ms const LIFETIME = 650; const BLEED = 64; // room around the button the canvas can draw into function createParticles(originX: number, width: number): Particle[] { return Array.from({ length: PARTICLE_COUNT }, (_, i) => { // Spread across the top edge, biased toward the press point. const spread = (Math.random() - 0.5) * Math.min(width, 120); const x = Math.min(Math.max(originX + spread, 4), width - 4); const side = x < width / 2 ? -1 : 1; const speed = 0.18 + Math.random() * 0.22; const angle = -Math.PI / 2 + side * Math.random() * 0.9; const isChip = i % 3 === 0; return { x, y: 0, vx: Math.cos(angle) * speed, vy: Math.sin(angle) * speed, angle: Math.random() * Math.PI, spin: (Math.random() - 0.5) * 0.02, w: isChip ? 5 : 3, h: isChip ? 2 : 3, }; }); } /** * Small chips of the button's own color fly off its top edge with gravity, * drag and spin, on one canvas that unmounts when the burst is over. */ function Burst({ originX, color, onDone, }: { originX: number; color: string; onDone: () => void; }) { const canvasRef = useRef(null); const onDoneRef = useRef(onDone); onDoneRef.current = onDone; useEffect(() => { const canvas = canvasRef.current; const ctx = canvas?.getContext("2d"); const parent = canvas?.parentElement?.parentElement; if (!(canvas && ctx && parent)) { return; } const dpr = window.devicePixelRatio || 1; const width = parent.offsetWidth; const cssW = width + BLEED * 2; const cssH = parent.offsetHeight + BLEED * 2; canvas.width = cssW * dpr; canvas.height = cssH * dpr; ctx.scale(dpr, dpr); const particles = createParticles(originX, width); const start = performance.now(); let last = start; let frame = 0; const tick = (now: number) => { const dt = Math.min(now - last, 32); last = now; const t = (now - start) / LIFETIME; ctx.clearRect(0, 0, cssW, cssH); if (t >= 1) { onDoneRef.current(); return; } ctx.fillStyle = color; ctx.globalAlpha = 1 - t * t; for (const p of particles) { p.vx *= 1 - DRAG * dt; p.vy = p.vy * (1 - DRAG * dt) + GRAVITY * dt; p.x += p.vx * dt; p.y += p.vy * dt; p.angle += p.spin * dt; ctx.save(); ctx.translate(p.x + BLEED, p.y + BLEED); ctx.rotate(p.angle); ctx.fillRect(-p.w / 2, -p.h / 2, p.w, p.h); ctx.restore(); } frame = requestAnimationFrame(tick); }; frame = requestAnimationFrame(tick); return () => cancelAnimationFrame(frame); }, [originX, color]); return ( ); } // --- Icons ----------------------------------------------------------------- function Spinner() { return ( ); } function Check() { return ( ); } // --- Button ---------------------------------------------------------------- function isPromiseLike(value: unknown): value is PromiseLike { return ( typeof value === "object" && value !== null && typeof (value as PromiseLike).then === "function" ); } export default function ParticleButton({ children = "Save changes", onClick, onSuccess, onError, status: controlledStatus, successDuration = 1600, errorDuration = 3200, pendingLabel = "Saving", successLabel = "Saved", errorLabel = "Try again", icon, particles = true, variant, size, className, disabled, ...props }: ParticleButtonProps) { const [internalStatus, setInternalStatus] = useState("idle"); const status = controlledStatus ?? internalStatus; const [burst, setBurst] = useState<{ id: number; originX: number; color: string; } | null>(null); const [width, setWidth] = useState(); const buttonRef = useRef(null); const contentRef = useRef(null); const pressXRef = useRef(null); const resetRef = useRef | null>(null); const runRef = useRef(0); const previousStatusRef = useRef(status); const shake = useAnimationControls(); const shouldReduceMotion = useReducedMotion(); useEffect( () => () => { if (resetRef.current) { clearTimeout(resetRef.current); } }, [] ); // The button's width follows its content. The entering label is measured // on every change and the outer width springs to it, so it never jumps. // The leaving label is skipped: it floats out on top, out of the flow. useLayoutEffect(() => { const button = buttonRef.current; const content = contentRef.current; if (!(button && content)) { return; } const measure = () => { const labels = content.querySelectorAll( `[data-label="${status}"]` ); const label = labels.item(labels.length - 1); if (!label) { return; } const style = getComputedStyle(button); const chrome = Number.parseFloat(style.paddingLeft) + Number.parseFloat(style.paddingRight) + Number.parseFloat(style.borderLeftWidth) + Number.parseFloat(style.borderRightWidth); setWidth(Math.ceil(label.scrollWidth + chrome)); }; measure(); const observer = new ResizeObserver(measure); observer.observe(content); return () => observer.disconnect(); }, [status]); // Success fires the burst and error shakes, whether the status came from // `onClick` or from the `status` prop. useEffect(() => { const previous = previousStatusRef.current; previousStatusRef.current = status; if (previous === status) { return; } const button = buttonRef.current; if (status === "success" && particles && !shouldReduceMotion && button) { const originX = pressXRef.current ?? button.offsetWidth / 2; setBurst({ id: Date.now(), originX, color: getComputedStyle(button).backgroundColor, }); } if (status === "error" && !shouldReduceMotion) { shake.start(SHAKE, { duration: 0.32, ease: "easeOut" }); } }, [status, particles, shouldReduceMotion, shake]); const settle = (next: "success" | "error") => { setInternalStatus(next); resetRef.current = setTimeout( () => { setInternalStatus("idle"); resetRef.current = null; }, next === "success" ? successDuration : errorDuration ); }; const handleClick = (event: MouseEvent) => { if (status === "pending") { return; } const rect = event.currentTarget.getBoundingClientRect(); // Keyboard clicks report 0,0, so they burst from the center. pressXRef.current = event.clientX === 0 && event.clientY === 0 ? null : event.clientX - rect.left; if (resetRef.current) { clearTimeout(resetRef.current); resetRef.current = null; } const result = onClick?.(event); if (event.defaultPrevented || controlledStatus !== undefined) { return; } if (!isPromiseLike(result)) { settle("success"); onSuccess?.(); return; } runRef.current += 1; const run = runRef.current; setInternalStatus("pending"); Promise.resolve(result).then( () => { if (run === runRef.current) { settle("success"); onSuccess?.(); } }, (error: unknown) => { if (run === runRef.current) { settle("error"); onError?.(error); } } ); }; const label = (() => { switch (status) { case "pending": return ( <> {pendingLabel} ); case "success": return ( <> {successLabel} ); case "error": return ( <> {errorLabel} ); default: return ( <> {children} {icon} ); } })(); return ( {burst && ( setBurst(null)} originX={burst.originX} /> )} {/* Clips the sliding labels to the button's box (the -my/py pair stretches it to full height) while the canvas can still overflow. */} {/* The entering label keeps its place in the flow (and so the measured width); the leaving one floats out on top of it. */} {label} {status === "pending" && pendingLabel} {status === "success" && successLabel} {status === "error" && errorLabel} ); }

Particle Button

On this page