Run Button
Freev1.0.0A start button that turns into its own stop control while an agent or job runs.
Build for your project
Code/install build
Usage
Import it and pass your content. The props that matter most are listed next.
Example
"use client";
import * as React from "react";
import { RunButton } from "@/components/ui/notchset/run-button";
const STEPS = ["plan", "search_docs", "read_file", "run_sql", "draft", "verify"];
/** onRun returns a promise: the key shows running until it settles, and the abort signal stops it. */
export function RunPlanner({ runAgent }: { runAgent: (signal: AbortSignal, onStep: (i: number) => void) => Promise<void> }) {
const [step, setStep] = React.useState(0);
return <RunButton legend="F4 · RUN" name="PLANNER" steps={STEPS} step={step} onRun={(signal) => runAgent(signal, setStep)} />;
}Props
onRun–(signal: AbortSignal) => unknownStarts the run. Return a Promise and the button tracks it; Stop aborts the signal.
onStop–() => voidCalled when the user stops the run.
state–"idle" | "running" | "stopped" | "complete"Controlled state. Uncontrolled, Stopped and Complete hold 2.8s, then return to idle.
steps–string[]The run's steps, drawn as nodes under the key.
step–numberThe current step index.
elapsedMs–numberElapsed time while running; counted by the button when omitted.
Show all 10 propsShow fewer
kbd–stringThe shortcut shown while idle (display only). Default "R".
legend / name–stringThe legend above the key; the first word of the idle status.
status–stringOverrides the status line.
labels–Partial<RunButtonLabels>Every word, for other languages.
Anatomy
- The Notchset instrument parts: node, legend, check and glyph flip.
- A native button; no primitive needed, so one file serves both builds.
- Plays tap, signal and done through beautiful-ui-sound when the page has it.
RunButtondata-slot="run-button"The key, its legend, the step track and the status line.
Keydata-slot="run-button-key"The button itself.
Trackdata-slot="run-button-track"The step nodes and their trace.
Source
components/ui/notchset/run-button.tsx
Loading the code
Build for your project
Code/install build
Installation
Base UI
pnpm dlx shadcn@latest add https://notchset.dev/r/run-button.jsonRadix
pnpm dlx shadcn@latest add https://notchset.dev/r/radix-nova/run-button.jsonFree, no account or key. Use the command for your project's primitives: a radix-*, new-york or default style in components.json is Radix, a base-* style is Base UI. With the @notchset registry added, @notchset/<name> picks for you.
Install by hand
- 1. No extra packages: React and Tailwind CSS v4 are enough.
- 2. Copy the files to these paths (the source, or save them all as a .zip)
- components/ui/notchset/run-button.tsx
- lib/beautiful-ui/notchset/instrument.tsx
- lib/beautiful-ui/notchset/root.ts
- 3. No stylesheet needed.
- 4. Install what it builds on first: shadcn's cn helper (lib/utils.ts, from npx shadcn init), the theme foundation (its tokens and base styles)
Styles didn't apply?
The CLI adds the styles to the CSS file named in components.json (tailwind.css). Check that it points at your global stylesheet, that the project uses Tailwind CSS v4, and that the file is imported in your root layout. Installed by hand: paste styles.css into that file.
For coding agents
Give your coding assistant the Markdown guide instead of screenshots.
Use it for
- Starting and stopping an agent or job from one place
- Showing which step a run is on without a separate progress bar
Use something else when
- A one-shot action that finishes instantly: use Button
- Long background jobs the user leaves: use a status row or Progress
Mistakes to avoid
- Pass `step` from your run's events; uncontrolled it stays on the first step
- Bind the shortcut yourself: `kbd` is only the hint
Agents find it by
- run agent, stop run, start stop button, run button, agent run control, elapsed time, step progress, Notchset
Where agents read it
- Guide for this component: https://notchset.dev/md/run-button.md
- Every component, for tools without MCP: /llms.txt
- MCP server:
https://notchset.dev/api/mcp(setup)
Behaviour
Keyboard
- Enter / Space
- Run, or stop a running run
Accessibility
- A native button with aria-pressed while running; its name switches between Run and Stop run
- The status line is a polite live region; flipping glyphs are hidden from screen readers, which hear the final text
- State reads from shape as well as colour: play, a filled stop square, an outline when stopped, a check when complete
Motion
- Press
- The key drops 1px in 40ms and springs back in 200ms cubic-bezier(.34,1.5,.5,1)
- Running
- The node blinks (r 3.25 ↔ 1.1 every 420ms); the readout ticks every 100ms; the trace fills the step track
- Complete
- The check traces in over 260ms; the step nodes pulse in order, 70ms apart
- Labels
- Glyph flip: characters cycle and land left to right, 14ms apart. Off under reduced motion
Responsive
- The key keeps its width while the label changes, so the row never reflows.
- Touch screens get a 44px key.
Performance
- The elapsed readout ticks on one interval only while running; idle and stopped do no work.
- Step changes swap text through the glyph flip, throttled to one frame at a time.
Changelog
v1.0.0 · 2026-10-02
First release
