Skip to content
Back

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-button
The code is part of Oxyn Pro

The preview stays free for everyone. Pro opens the code of every Pro component, screen, agent-app template, block and kit, plus the Pro CLI.

Get Pro

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.

Terminal
oxyn add icon-button

Usage

Dioxus · rust
The code is part of Oxyn Pro

The preview is free. Pro opens the code of every Pro component, screen and template.

Get Pro

Examples

Ghost

Quiet toolbar action.

Code Pro
The code is part of Oxyn Pro

The preview is free. Pro opens the code of every Pro component, screen and template.

Get Pro

Secondary badge

Outlined, with an unread count.

Code Pro
The code is part of Oxyn Pro

The preview is free. Pro opens the code of every Pro component, screen and template.

Get Pro

Primary xl

The large round action on mobile.

Code Pro
The code is part of Oxyn Pro

The preview is free. Pro opens the code of every Pro component, screen and template.

Get Pro

Toggle

aria-pressed toggle whose icon morphs.

Code Pro
The code is part of Oxyn Pro

The preview is free. Pro opens the code of every Pro component, screen and template.

Get Pro

API reference

IconButton

PropTypeDefaultDescription
iconrequiredString—Icon.
labelrequiredString—Accessible name and tooltip.
variantString"ghost"`ghost` · `secondary` · `primary`.
sizeString"md"`xs` (16) · `sm` (28) · `md` (32) · `lg` (36) · `xl` (40).
pressedOption<bool>Default::default()Toggle state (`aria-pressed`); `None` = a plain action.
pressed_iconOption<String>Default::default()Icon shown while pressed (copy → check, mic → stop).
badgeOption<u64>Default::default()Badge: `Some(0)` = dot, `Some(n)` = count.
disabledboolDefault::default()Disabled.
stateOption<String>Default::default()Review sheets: force a state.
onclickEventHandler<()>—Pressed.

Read from the Rust signature and doc comments.

Keyboard interactions

KeyAction
EnterorSpacePress or toggle
TabFocus 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>; GPUI Role::Button with 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 expose aria-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.snap and 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
TransitionDurationDelayEasing / springFrame rate
Hover colour / shadow120 ms (dur.fast)0ease.out60 Hz
Press scale80 ms (dur.instant)0ease.out60 Hz
Width glide on label change214 ms (spring.snap)0spring60 Hz
Label crossfade + blur180 ms (dur.base)0ease.out60 Hz
Loading shimmer band1400 ms loop (dur.shimmer.sweep)0linear30 Hz
Spinner750 ms / turn0linear60 Hz
Hold fill / drain1200 ms / 200 ms (dur.approval.hold/drain)0linear / ease.out60 Hz
Success hold (reset_after)1600 ms (Oxyn plus: user-set)———
Retry back-offbackoff × 2ⁿ, max 30 safter failure1 Hz countdown1 Hz
Check draw240 ms (dur.check.draw)0ease.out60 Hz
Reduced motionno 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 Pending is ignored (core returns false), so a slow action can't run twice. Back-off presses are ignored until the countdown ends.
  • Tiny sizes: xs drops 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 IconButton from oxyn_dioxus and include PRIMITIVES_CSS plus the token stylesheet once.
  • A GPUI version exists: IconButtonEl in oxyn_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.

Guides

Oxyn · 74 free components · 264 Pro components · 96 screens · 20 blocks · Dioxus and GPUI