Button
Eight variants and five sizes, with a shimmering loading state, a progress fill, press-and-hold for destructive actions and a shortcut chip.
oxyn add buttonrsx! {
Button {
label: "Deploy",
onclick: move |_| deploy(),
}
}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
Button is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add buttonuse crate::oxyn::{Button, PRIMITIVES_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{Button, PRIMITIVES_CSS};
Usage
rsx! {
Button {
label: "Deploy",
onclick: move |_| deploy(),
}
}Examples
Primary
The one main action on a surface.
Code
rsx! {
Button {
label: "Deploy",
onclick: move |_| deploy(),
}
}Secondary
Second action next to a primary.
Code
rsx! {
Button {
label: "Preview",
variant: "secondary",
onclick: move |_| deploy(),
}
}Destructive hold
Press and hold to confirm a delete.
Code
rsx! {
Button {
label: "Hold to delete",
variant: "destructive",
icon: "trash",
hold: true,
onclick: move |_| deploy(),
}
}Loading progress
Keeps its width while it works and fills with progress.
Code
rsx! {
Button {
label: "Uploading",
variant: "secondary",
loading: true,
loading_style: "progress",
progress: 0.64,
onclick: move |_| deploy(),
}
}Shortcut
Shortcut chip, spelled out for screen readers.
Code
rsx! {
Button {
label: "Run",
icon: "play",
shortcut: "Mod+Enter",
onclick: move |_| deploy(),
}
}API reference
Button
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | String | — | Label. |
variant | String | "primary" | `primary` · `secondary` · `ghost` · `destructive` · `outline` · `link` · `quiet` · `success`. |
size | String | "md" | `xs` · `sm` · `md` · `lg` · `xl`. |
loading | bool | Default::default() | Busy: keeps its width, ignores presses, `aria-busy`. |
loading_style | String | "shimmer" | `shimmer` (spinner + band) · `spinner` · `progress`. |
progress | Option<f32> | Default::default() | Progress 0..1 for the `progress` loading style. |
icon | Option<String> | Default::default() | Leading icon. |
icon_right | Option<String> | Default::default() | Trailing icon. |
disabled | bool | Default::default() | Disabled. |
reason | Option<String> | Default::default() | Why it is disabled (tooltip and `aria-describedby` text). |
hold | bool | Default::default() | Press and hold to confirm (destructive actions). |
shortcut | Option<String> | Default::default() | Shortcut chip ("Mod+Enter"). |
full | bool | Default::default() | Stretch to the container. |
state | Option<String> | Default::default() | Review sheets: force `hover`, `pressed` or `focus`. |
onclick | EventHandler<()> | — | Pressed (or the hold completed). |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| EnterorSpace | Press |
| Space (held) | Hold-to-confirm buttons fill while held and fire when full |
| Tab | Disabled-with-reason buttons stay focusable so the reason can be read |
Accessibility
- Native button element with type=button.
- Loading sets aria-busy and aria-disabled; focus stays on the button.
- A disabled button with a reason keeps focus and exposes the reason through aria-describedby.
- Shortcuts are exposed with aria-keyshortcuts; the visible chip is hidden from screen readers.
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
- Keeps its width while loading, so rows never jump.
- full stretches it to the container (mobile sheets, narrow side panels).
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
Buttonfromoxyn_dioxusand includePRIMITIVES_CSSplus the token stylesheet once. - A GPUI version exists:
ButtonElinoxyn_gpui. - Props to set first:
label. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.