Stateful message button, animated React component
A button that shows its own async work: idle, loading, success and error. Pressed it squashes, a light sweeps across while the promise runs and the label rolls with the width springing to fit; success turns it green with a small overshoot pop and a drawn check, failure turns it red and shakes.
- Free
- Motion Effects
- Spring
Taps on press, chimes on success and bumps on error. Sound is off on this site until you switch it on.
Like Stateful message button? 256 more are in Pro.
Pro unlocks all 256 Pro components, every template and block, and everything we release next. Stateful message button stays free.
Play with it
Move the controls and watch it change. Copy code gives you a snippet with only the props you changed.
Props
| Prop | Type | Default | What it does |
|---|---|---|---|
| children | React.ReactNode | — | Idle label. |
| onClick | () => Promise<void> | void | — | Runs on click. Return a promise to show the loading state until it settles; throw to show the error state. |
| loadingText | string | "Loading" | Label while onClick is pending. |
| successText | string | "Done" | Label after onClick resolves. |
| errorText | string | "Something went wrong" | Label after onClick rejects. |
| resetDelay | number | 1800 | How long success or error stays before the button resets, in ms. |
| showSuccess | boolean | true | Show the success state; otherwise go straight back to idle. |
| variant | "default" | "outline" | "ghost" | "destructive" | "default" | Visual style of the idle and loading states. |
| size | "sm" | "md" | "lg" | "md" | Height, padding and text size. |
| icon | React.ReactNode | — | Icon before the idle label. |
| successIcon | React.ReactNode | — | Replaces the drawn check. |
| errorIcon | React.ReactNode | — | Replaces the drawn alert. |
| autoplay | boolean | false | Loops through loading and success (without calling onClick) until someone presses it. |
| enableSound | boolean | true | Plays interface sounds on interaction. They follow the sound switch (setSoundsEnabled, on by default) and stay silent on hover. Autoplay makes the same sounds once the visitor has used the page. Pass false to silence this component. |
Add it to your project
- 1
Set up your project once
You need a Next.js project with Tailwind CSS and the
@/import alias. In its root folder, run this once. It createscomponents.jsonand thecn()helper insrc/lib/utils.ts:npx shadcn@latest init -d
Starting from nothing? The Quick Start walks through the whole thing.
- 2
Connect the registry
Run this once per project. It writes the Nexus UI entry into
components.jsonfor you:npx shadcn@latest registry add "@nexus-labs=https://www.nexus-ui.com/api/registry/{name}"Type it exactly as shown.
{name}is filled in by the CLI with the component you ask for, so you never replace it.
- 3
Add the component
Run this from your project root. It adds the component, the helpers it imports and its npm packages.
npx shadcn@latest add @nexus-labs/stateful-button
- 4
Check what was added
With a project made as in the Quick Start (a
src/folder), these files land in it:components/stateful-button.tsxstateful-button/index.tsstateful-button.tsx - 5
Copying by hand? Skip the registry
Instead of steps 2 and 3 you can copy the files yourself, with no registry and no API key. Step 1 still applies, so that
cn()exists. Install the packages:npm install framer-motion
Then show the source and create each file at the path it gives:
- 6
Use it in a page
Installing only adds the files. Import the component in a page and render it. The Usage tab on the preview shows a fuller example with props:
// src/app/page.tsx import { StatefulButton } from "@/components/stateful-button"; export default function Page() { return ( <main> <StatefulButton /> </main> ); }
Like Stateful message button? 256 more are in Pro.
Pro unlocks all 256 Pro components, every template and block, and everything we release next. Stateful message button stays free.
About Stateful message button
The Stateful Message Button transitions through idle, loading, success, and error states using Framer Motion layout animations. Text and icon transitions between states keep the button width stable to prevent layout shift. The success checkmark and error cross animate in with spring physics. It accepts a standard onClick async function and manages its own state machine internally, making it a direct drop-in for any form submission or API action button in a Next.js application.
Good for
- Form submit and save buttons
- API action and mutation buttons
- File upload and download triggers
- Async operation initiators
Stateful message button questions
Does it make sound, and how do I turn it off?
Taps on press, chimes on success and bumps on error. Sounds are synthesised with the Web Audio API, so there are no audio files, and they only play after a click or key press. Pass `enableSound={false}` to silence this component, or call `setSoundsEnabled(false)` from `@/lib/ui-sounds` to switch every sound off at once. The CLI installs `@/lib/ui-sounds` with the component.