particle button.md

Particle Button

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

Source: https://kokonutui.com/docs/buttons/particle-button

Installation

npx shadcn@latest add @kokonutui/particle-button

Props

Prop Type Default Description
children? ReactNode "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 1600 How long (ms) the success state shows before going back to idle.
errorDuration? number 3200 How long (ms) the error state shows. Longer than success, so it can be read.
pendingLabel? ReactNode "Saving"
successLabel? ReactNode "Saved"
errorLabel? ReactNode "Try again"
icon? ReactNode Icon rendered after the idle label.
particles? boolean 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" >, VariantProps<typeof buttonVariants>.

ParticleButtonStatus

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

Source

"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<typeof buttonVariants> {
  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<HTMLButtonElement>) => 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] };
// A computed color with zero alpha: rgba(0, 0, 0, 0) or oklch(… / 0).
const ZERO_ALPHA = /(,|\/)\\s*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<HTMLCanvasElement>(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 (
    <span
      aria-hidden="true"
      className="pointer-events-none absolute"
      style={{
        top: -BLEED,
        left: -BLEED,
        width: `calc(100% + ${BLEED * 2}px)`,
        height: `calc(100% + ${BLEED * 2}px)`,
      }}
    >
      <canvas className="block h-full w-full" ref={canvasRef} />
    </span>
  );
}

// --- Icons -----------------------------------------------------------------

function Spinner() {
  return (
    <svg
      aria-hidden="true"
      className="animate-spin [animation-duration:700ms]"
      fill="none"
      viewBox="0 0 16 16"
    >
      <circle
        cx="8"
        cy="8"
        opacity="0.25"
        r="6"
        stroke="currentColor"
        strokeWidth="2"
      />
      <path
        d="M14 8a6 6 0 0 0-6-6"
        stroke="currentColor"
        strokeLinecap="round"
        strokeWidth="2"
      />
    </svg>
  );
}

function Check() {
  return (
    <svg aria-hidden="true" fill="none" viewBox="0 0 16 16">
      <motion.path
        animate={{ pathLength: 1 }}
        d="M3.5 8.5 6.5 11.5 12.5 4.5"
        initial={{ pathLength: 0 }}
        stroke="currentColor"
        strokeLinecap="round"
        strokeLinejoin="round"
        strokeWidth="2"
        transition={{ duration: 0.3, delay: 0.08, ease: EASE_OUT }}
      />
    </svg>
  );
}

// --- Button ----------------------------------------------------------------

// Chips take the button's fill; outline, ghost and link buttons have none, so
// those burst in the text color instead.
function burstColor(button: HTMLElement) {
  const style = getComputedStyle(button);
  const fill = style.backgroundColor;
  const clear = fill === "transparent" || ZERO_ALPHA.test(fill);
  return clear ? style.color : fill;
}

function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
  return (
    typeof value === "object" &&
    value !== null &&
    typeof (value as PromiseLike<unknown>).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<ParticleButtonStatus>("idle");
  const status = controlledStatus ?? internalStatus;
  const [burst, setBurst] = useState<{
    id: number;
    originX: number;
    color: string;
  } | null>(null);
  const [width, setWidth] = useState<number | undefined>();

const buttonRef = useRef<HTMLButtonElement>(null);
  const contentRef = useRef<HTMLSpanElement>(null);
  const pressXRef = useRef<number | null>(null);
  const resetRef = useRef<ReturnType<typeof setTimeout> | 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<HTMLElement>(
        `[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: burstColor(button),
      });
    }
    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<HTMLButtonElement>) => {
    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 (
          <>
            <Spinner />
            {pendingLabel}
          </>
        );
      case "success":
        return (
          <>
            <Check />
            {successLabel}
          </>
        );
      case "error":
        return (
          <>
            <AlertCircle aria-hidden="true" />
            {errorLabel}
          </>
        );
      default:
        return (
          <>
            {children}
            {icon}
          </>
        );
    }
  })();

return (
    <MotionConfig reducedMotion="user">
      {/* Outside the button, so it isn't read twice as part of its name. */}
      <span aria-live="polite" className="sr-only">
        {status === "pending" && pendingLabel}
        {status === "success" && successLabel}
        {status === "error" && errorLabel}
      </span>
      <motion.button
        animate={width === undefined ? undefined : { width }}
        aria-busy={status === "pending" || undefined}
        aria-disabled={status === "pending" || undefined}
        className={cn(
          buttonVariants({ variant, size }),
          "group/status relative overflow-visible",
          "transition-[background-color,color,opacity] duration-200 ease-out",
          status === "error" &&
            "bg-red-600 text-white hover:bg-red-600/90 dark:bg-red-500 dark:text-white dark:hover:bg-red-500/90",
          className
        )}
        data-status={status}
        disabled={disabled}
        onClick={handleClick}
        ref={buttonRef}
        transition={shouldReduceMotion ? { duration: 0 } : WIDTH_TRANSITION}
        type="button"
        {...props}
      >
        {burst && (
          <Burst
            color={burst.color}
            key={burst.id}
            onDone={() => 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. */}
        <motion.span
          animate={shake}
          className="relative -my-2 flex items-center justify-center self-stretch overflow-hidden py-2"
          ref={contentRef}
        >
          {/* The entering label keeps its place in the flow (and so the
              measured width); the leaving one floats out on top of it. */}
          <AnimatePresence initial={false} mode="popLayout">
            <motion.span
              animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
              className="inline-flex shrink-0 items-center gap-2 whitespace-nowrap"
              data-label={status}
              exit={{ opacity: 0, y: -8, filter: "blur(2px)" }}
              initial={{ opacity: 0, y: 8, filter: "blur(2px)" }}
              key={status}
              transition={LABEL_TRANSITION}
            >
              {label}
            </motion.span>
          </AnimatePresence>
        </motion.span>
      </motion.button>
    </MotionConfig>
  );
}