Components › Forms & input › Button › Icon button

Icon button

canon

Square button carrying only an icon; label lives in the tooltip. Quiet at rest, variant="framed" for the bordered one, variant="secondary" (beta) for a hairline-bordered tool row.

variant="secondary" has ONE size (owner 19 Oct 2026, acrm ACRM-542): --control-h square + --ico-sm glyph; size/iconSize are ignored; text beside a row uses .acrm-icobtn-text (padding-inline --sp-4). Window headers stay quiet (AD 27 Sep 2026). variant="framed" (11 September 2026, BTN-A3) is a 1:1 port of the hand-drawn .pr-iconbtn / .rr-iconbtn, which were deleted with it: 32px wide on the base height, 1px --border-strong, --surface-100, --shadow-xs, --ico-sm glyph in --ink-700, hover --surface-75. Pressed, open and disabled deliberately keep the rest look, because the hand-drawn rules had no such states; the validator rule iconbtn-framed-raw blocks the old classes. Variant by CONTEXT (AD 26 Sep 2026, acrm !3910 — in the docstring): dense list row (ItemList, timeline, relations, thread, project/meeting/milestone row) = quiet size="sm"; detail header / toolbar = quiet default; variant="framed" ONLY next to framed siblings (rail action row, section header next to framed buttons, dialog footer next to Button default). Kebab = dots-vertical; a kebab with one item is replaced by the direct action (trash + confirm, link-off without danger) — rule "kebab with one action" landed as the wave C cleanup (AD 26 Sep 2026, acrm !3997: ProjectMilestonesSection trash, IdentityImageDialog trash, ProjectMeetingsTab link-off, none get a Popover around a single choice). Wave 16 (acrm !3997) finished the context rule above by migrating the last hand-drawn icon buttons onto it: 32px `.icobtn` (Uživatelé domains, segment detail/share ×2) → framed size default (30); 22px `.eml-icobtn` (draft/pinned mail rows) → `size="sm"`; 26px `.aichat-hbtn` (assistant panel header) → default, with `pressed` for the settings toggle; TabStrip scroll arrows → `size="sm"`. Exception kept: the App shell chrome's 32px `.as-icobtn` / `.as-util .icobtn` sits among 32–34px neighbours and stays hand-drawn. State pressed (acrm !3936): pressed?: boolean → aria-pressed + --active-surface, also on hover — for toggles (format, panel, template/AI in mail compose). The open look applies only to menu triggers ([aria-expanded=true][aria-haspopup]); a disclosure (collapse/expand) carries its state in the glyph. Link (`href`, AD 27 Sep 2026 — attachment download): renders `<a class="acrm-icobtn …">` with the same look, same pattern as `<Button href>` — real link semantics (middle-click, "save link as", a screen reader announces a link), `target="_blank"` gets `rel="noopener noreferrer"` merged in, `disabled` with `href` renders `<a aria-disabled>` without `href` (a link cannot be disabled by attribute). External/file URLs only — in-app navigation stays on the router. `ref` forwards onto the `<a>` too (review fix in !3997), so it can anchor a Popover. Touch target (owner 8 Oct 2026, acrm !4882, RULES §19): below 720 px an invisible ::after makes the tap area ≥ 44 × 44 without changing the look; checked on dev 8 Oct (⋮ top bar 42×44 at the screen edge, 0 stolen taps). Clipped targets fixed in acrm !4892 (checked on dev 8 Oct: Ajda 78×44, Pošta stars 44×44 except a row cut by the scroll edge). Remaining by design: column-header ⋮ 24×40 (header row is 40 px). Registry repaired 17 Oct 2026 (review F6): added exported Icon to react[].

Used in 474 files · 154 areas · 1727× — components/AiBadge, components/AppShell, components/Board, components/CallbackTakeoverModal, components/CheckMenu, components/DuplicatesPanel …

@acrm/ui <IconButton> <Icon>.acrm-icobtn .acrm-icobtn.sm .acrm-icobtn.framed .acrm-icobtn.secondarySourceStoryLegacy card buttons.html
ExamplesCodeUsageAccessibilityChangelog

Keyboard

  • Native <button>: Tab focuses, Enter and Space activate. With href it is a native <a> instead: Tab focuses, Enter activates, and it also gets middle-click / "open in new tab" / "save link as" for free.
  • disabled removes it from the tab order (native <button disabled>); with href there is no native way to disable a link, so disabled instead renders <a aria-disabled="true"> with no href — it stays in the tab order but does nothing, so a screen reader user is not routed to a dead end silently. Prefer omitting the action instead of a disabled link where the screen allows it.
  • Default type="button" — pressing Enter inside a form does not submit through it.

ARIA

  • No role needed — native <button> or, with href, native <a>.
  • The button has no text, so the accessible name must come from aria-label (preferred) or title. Without one the button is announced as "button" (or "link") only.
  • Do not rely on the icon's SVG for a name — <Icon> is decorative.
  • pressed renders aria-pressed (acrm !3936) — for toggles (format, panel, template/AI in mail compose). It is not used for a menu trigger's open state, which comes from aria-expanded/aria-haspopup on the trigger instead.

Focus

  • Foundation ring from ds.css: 2px solid var(--accent), outline-offset: 1px, following --radius-sm.
  • No component-specific focus style; hover background is not a focus indicator.

Contrast

Ratios computed from packages/ui/src/tokens/tokens.css:

  • Icon at rest --fg-secondary on canvas: #7d8184 on #ffffff = 3.93:1 (light); #9a9ca1 on #1b1c1f = 6.20:1 (dark). Light theme passes the 3:1 minimum for graphical objects, not AA 4.5:1 for text (the icon is a graphic).
  • Icon on hover --fg: 17.59:1 (light), 14.53:1 (dark).
  • Focus ring --accent on canvas: 4.44:1 (light), 3.83:1 (dark).

Known limits

  • Rest-state icon contrast in light theme is 3.93:1 — meets the non-text minimum only.
  • sm size (24px) meets the 24 × 24 CSS px target minimum exactly, with no margin to spare; keep --sp-2 or more between adjacent sm buttons.
  • No built-in tooltip beyond the native title; touch users get no tooltip at all, so the icon must be unambiguous.

Source: docs/button/icon-button.a11y.md · GitLab