Icon ButtonPro
A square button that is only an icon: ghost, secondary or primary, five sizes, a toggle that morphs its icon, a dot or count badge.
oxyn add icon-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
Icon 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 icon-buttonUsage
The preview is free. Pro opens the code of every Pro component, screen and template.
Examples
Ghost
Quiet toolbar action.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
Secondary badge
Outlined, with an unread count.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
Primary xl
The large round action on mobile.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
Toggle
aria-pressed toggle whose icon morphs.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
API reference
IconButton
| Prop | Type | Default | Description |
|---|---|---|---|
iconrequired | String | — | Icon. |
labelrequired | String | — | Accessible name and tooltip. |
variant | String | "ghost" | `ghost` · `secondary` · `primary`. |
size | String | "md" | `xs` (16) · `sm` (28) · `md` (32) · `lg` (36) · `xl` (40). |
pressed | Option<bool> | Default::default() | Toggle state (`aria-pressed`); `None` = a plain action. |
pressed_icon | Option<String> | Default::default() | Icon shown while pressed (copy → check, mic → stop). |
badge | Option<u64> | Default::default() | Badge: `Some(0)` = dot, `Some(n)` = count. |
disabled | bool | Default::default() | Disabled. |
state | Option<String> | Default::default() | Review sheets: force a state. |
onclick | EventHandler<()> | — | Pressed. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| EnterorSpace | Press or toggle |
| Tab | Focus shows the label as a tooltip |
Accessibility
- Always carries aria-label; the same text is its tooltip.
- Toggles expose aria-pressed.
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
- Five sizes from 16 px (xs, dense IDE toolbars) to 40 px (xl).
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
IconButtonfromoxyn_dioxusand includePRIMITIVES_CSSplus the token stylesheet once. - A GPUI version exists:
IconButtonElinoxyn_gpui. - Props to set first:
icon,label. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.