Action buttonPro
A button that runs something and reports back: idle, pending with a spinner, a check on success, an error that retries with back-off.
oxyn add action-buttonThe preview stays free for everyone. Pro opens the code of every Pro component, screen, agent-app template, block and kit, plus the Pro CLI.
Rendered from Rust at build time · goes live when visible
When to use
- The one control every surface uses to act: send, approve, run, retry, open.
- Agent apps press buttons while something is *already happening*, so a button has to say "busy", "not now, and why", "done" and "failed, try again in 4 s" without changing size or moving its neighbours.
- The icon button is the same control at toolbar density, named by its tooltip.
- The action button is a self-contained press → pending → done / failed loop for frequent toolbar actions (deploy, sync, run evals).
When not to use
- Send, stop, queue and steer in one control, in twelve styles: use Send control instead.
- A main action with a menu of alternatives: use Split button instead.
- A small label for one control: use Tooltip instead.
Installation
Action button is part of Oxyn Pro; the preview is free. Pro items install with the oxyn CLI once your licence is signed in; until then Pro members copy the code from this page.
oxyn add action-buttonUsage
The preview is free. Pro opens the code of every Pro component, screen and template.
Examples
Idle
Ready to run.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
Pending
Spinner after a short delay.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
Success
Check and past tense.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
Retry backoff
Failed; retries after a counted back-off.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
API reference
ActionButton
| Prop | Type | Default | Description |
|---|---|---|---|
modelrequired | ActionModel | — | Model. |
nowrequired | ClockMs | — | Clock. |
icon | String | "up" | Icon at rest. |
shortcut | Option<String> | Default::default() | Shortcut hint chip (Oxyn plus). |
on_press | EventHandler<()> | — | Pressed (ignored while pending or backing off). |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| EnterorSpace | Run |
| Shortcut | The chip's shortcut runs it from anywhere on the page |
Accessibility
- Results are announced through a polite live region inside the button.
- Pending sets aria-busy; the label changes to the present tense.
From the spec
- Native
<button type=button>; GPUIRole::Buttonwith the label as the accessible name. - Icon buttons always carry
aria-label(= tooltip text). - Loading:
aria-busy=true+aria-disabled=true; focus stays on the button so keyboard users don't lose their place. Disabled-with-reason stays focusable and exposes the reason. - Toggle icon buttons expose
aria-pressed. Shortcuts exposearia-keyshortcuts. - Action results are announced through a polite live region inside the button.
- Contrast: primary is white-on-black (dark: black-on-white) ≥ 15:1; secondary text ≥ 7:1. Destructive and success use the status tokens, which meet 4.5:1 on their fills.
Motion & interaction
- Press. Scales to 97 % in 80 ms on press, back on release (icon-only buttons 94 %, Arc). Never bounces (motion.md: presses do not overshoot).
- Label / icon change. The width glides to the new size on
spring.snapand the new content Fades in out of a 3 px blur. Action button labels rise 5 px as they fade in. - Loading. The left icon becomes a 750 ms arc spinner; a highlight band sweeps the label every 1.4 s (shimmer). The button keeps its width so the layout never jumps.
- Hold. A fill runs left → right for 1.2 s; releasing drains it in 200 ms; completing fires once.
- Success check draws itself in 240 ms. Icon morph (copy → check, mic → stop) scales from 60 % with a −20° turn.
- Badge on an icon button: a dot (unread) or a count, ringed in the page colour so it reads on any surface.
Timing
| Transition | Duration | Delay | Easing / spring | Frame rate |
|---|---|---|---|---|
| Hover colour / shadow | 120 ms (dur.fast) | 0 | ease.out | 60 Hz |
| Press scale | 80 ms (dur.instant) | 0 | ease.out | 60 Hz |
| Width glide on label change | 214 ms (spring.snap) | 0 | spring | 60 Hz |
| Label crossfade + blur | 180 ms (dur.base) | 0 | ease.out | 60 Hz |
| Loading shimmer band | 1400 ms loop (dur.shimmer.sweep) | 0 | linear | 30 Hz |
| Spinner | 750 ms / turn | 0 | linear | 60 Hz |
| Hold fill / drain | 1200 ms / 200 ms (dur.approval.hold/drain) | 0 | linear / ease.out | 60 Hz |
Success hold (reset_after) | 1600 ms (Oxyn plus: user-set) | — | — | — |
| Retry back-off | backoff × 2ⁿ, max 30 s | after failure | 1 Hz countdown | 1 Hz |
| Check draw | 240 ms (dur.check.draw) | 0 | ease.out | 60 Hz |
| Reduced motion | no press scale; label swaps with an 80 ms fade; shimmer off (static label); spinner slows to 2.4 s per turn instead of freezing; hold keeps its 1.2 s but fills in steps | — | linear | — |
Responsive behaviour
- Sits inline in toolbars and forms like a regular button.
Edge cases (spec)
- Long labels never wrap; the button grows. In a constrained toolbar the host truncates with an ellipsis and the full label goes to
title. - Label change while loading keeps the loading width until loading ends, then glides once.
- Double press during
Pendingis ignored (core returnsfalse), so a slow action can't run twice. Back-off presses are ignored until the countdown ends. - Tiny sizes:
xsdrops the gap to 4 px and the icon to 12 px; icon buttons under 20 px keep a 24 px hit area through padding in the host. - Touch: no hover state; press scale still applies. Hold uses pointer capture semantics: leaving the button cancels and drains.
- RTL: icon order follows the inline direction (flex). The hold fill runs from the inline start.
- Very fast actions (< 300 ms) still show the success state for the full hold so it is seen.
Notes for AI
- Import
ActionButtonfromoxyn_dioxusand includePRIMITIVES_CSSplus the token stylesheet once. - A GPUI version exists:
ActionButtonElinoxyn_gpui. - Props to set first:
model,now. - It reads a clock (
now) for live timers; pass one clock for the whole page rather than one per component. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.