Icon button | Arcadia Design

Describe a change, @ to add files

import { IconButton } from "@arcadia/ui";

<IconButton icon="copy" label="Copy message" tone="muted" shortcut="mod+c" />
<IconButton icon="revert" label="Restore checkpoint" tone="muted" />
<IconButton icon="more" label="More actions" tone="muted" />

Message actions are ghost and muted. In the composer, + is the secondary disc and send the inverse one.

TSX

import { IconButton } from "@arcadia/ui";

<IconButton icon="new-chat" label="New chat" shortcut="mod+n" onClick={newChat} />

label is required: it becomes the aria-label and the tooltip's title, because a tooltip is not a label. The default size is sm (24px). Compose it as a popup trigger with render: <MenuTrigger render={<IconButton icon="more" label="More" />} />. A dot-only glyph (more) draws at --icon-1 whatever the tone: at the muted rank its three dots peak under the row's own secondary line and read as specks.

Examples

Tooltips

Hover or focus: the title, a glyph shortcut as key caps, and an optional subtitle. Use tooltip={false} when the label is already visible beside it.

import { IconButton } from "@arcadia/ui";

<IconButton icon="settings" label="Settings" shortcut="⌘," />
<IconButton
  icon="plus"
  label="Add context"
  variant="secondary"
  shape="pill"
  tooltip={{ subtitle: "Files, images and modes" }}
/>
<IconButton icon="sidebar" label="Toggle sidebar" tooltip={false} />

Toggle

pressed draws the hover fill and sets aria-pressed; the glyph stays the same outline. An open popup lights the trigger the same way.

import { useState } from "react";
import { IconButton } from "@arcadia/ui";

function Toggle() {
  const [open, setOpen] = useState(false);
  return (
    <IconButton icon="sidebar" label="Toggle panel" pressed={open} onClick={() => setOpen(!open)} />
  );
}

Busy, stop and send

loading swaps the glyph for a spinner and keeps focus.

import { IconButton } from "@arcadia/ui";

<IconButton icon="refresh" label="Refresh" loading />
<IconButton icon="stop" label="Stop" variant="inverse" shape="pill" />
<IconButton icon="arrow-up" label="Send" variant="inverse" tone="plan" shape="pill" />

The inverse disc is send, and stop while a turn runs; tone="plan" turns it Plan mode's distance blue, because the beacon stays a light. Disabled, send stays a visible disc, so an empty composer still shows where it is.

Variant and stateShow interaction states

RestToggledMenu openDisabledLoadingGhost

Ghost, muted

Secondary pill

Inverse pill

Ghost, plan

Inverse, plan

Size and variant

GhostGhost, mutedSecondary pillInverse pillGhost, planInverse, planExtra small

Small

Medium

Large

rootStyle takes where the button sits (margins, self-alignment, flex and grid placement, size bounds) and the knobs below, each a token of its kind. A colour, a raw length or any other property is a type error: a look that comes up twice becomes a variant.

TSX

import * as stylex from "@stylexjs/stylex";

const styles = stylex.create({
  // a copy button that turns success-green once it has copied
  copied: { "--ib-fg": "var(--text-success)", "--ib-fg-hover": "var(--text-success)" },
});

<IconButton icon="check" label="Copied" tone="muted" rootStyle={styles.copied} />

--ib-size: Ref<Control | IconSize>Default var(--control-sm); Box width and height.
--ib-radius: Ref<Radius>Default var(--radius-md); Corner radius (a pill is full).
--ib-icon: Ref<IconSize>Default var(--icon-md); Glyph and spinner size.
--ib-bg: PaintDefault transparent; Fill at rest.
--ib-bg-hover: PaintDefault var(--fill-4); Fill under the pointer.
--ib-bg-open: PaintDefault var(--ib-bg-hover); Fill when toggled on (pressed) or while its popup is open.
--ib-bg-disabled: PaintDefault transparent; Fill when disabled.
--ib-fg: PaintDefault var(--icon-2); Glyph colour at rest.
--ib-fg-hover: PaintDefault var(--icon-1); Glyph colour under the pointer.
--ib-fg-open: PaintDefault var(--ib-fg-hover); Glyph colour when toggled on or open.
--ib-fg-disabled: PaintDefault var(--icon-4); Glyph colour when disabled.
--ib-border: PaintDefault transparent; A 1px inset ring. Default transparent.

Variants, tones and sizes only reassign knobs, and each state reads its own (--ib-bg-hover, --ib-fg-disabled), so a knob you set never drops a state. A toggled-on button and an open popup's trigger share the --ib-*-open pair.

label is the whole accessible name. shortcut shows in the tooltip and is exposed as aria-keyshortcuts ("⌘N" reads as Meta+N), never as part of the name; binding the key is yours. Tooltips open after 350ms, and once one has shown, its neighbours open instantly for 200ms.

A disabled icon button can't be focused, so its tooltip never shows. When it needs to say why, add focusableWhenDisabled so it stays focusable with aria-disabled.

EnterSpace: Activate

IconButton

iconrequired: IconName
labelrequired: string; Required: becomes aria-label and the tooltip title. A tooltip is not a label.
shortcut: string | readonly string[]; Shown in the tooltip and exposed as aria-keyshortcuts: "⌘N", ["⌘","N"], "mod+n", "⏎".
variant: "ghost" | "secondary" | "inverse"Default "ghost"; ghost; secondary, a fill-3 disc (a composer's +); inverse, an ink disc (send and stop).
tone: "neutral" | "muted" | "plan"; muted drops the glyph one rank (icon-3); plan is Plan mode's distance blue (on inverse, a blue disc: the plan-mode send). A dot-only glyph (more) takes no rank: it draws at label ink (icon-1) whatever the tone.
size: "xs" | "sm" | "md" | "lg"Default "sm"; Boxes 20 / 24 / 28 / 32.
shape: "rounded" | "pill"Default "pill"
pressed: boolean; Toggle state: aria-pressed + data-pressed (drawn like an open popup's trigger: --ib-bg-open).
loading: booleanDefault false; Busy: the glyph becomes a spinner, aria-busy, activation blocked, focus kept.
flush: boolean; Negative margin of (box − glyph) / 2 so the glyph aligns optically with neighbouring text edges.
tooltip: false | IconButtonTooltipOptions; Tooltip options, or false for none (e.g. when the label is already visible next to it).
rootStyle: IconButtonStyle; Typed StyleX override: where the button sits and its --ib-* knobs.
render: RenderProp<{ disabled: boolean }>; Replace the rendered element, e.g. render={<a href="/settings" />}, or a function of props and state.
disabled: boolean; Native disabled: no pointer events, no tooltip, skipped by Tab.
focusableWhenDisabled: boolean; Keep a disabled control focusable and hoverable (aria-disabled), so a tooltip can say why.
nativeButton: boolean; Button semantics, inferred from what renders: a <button> is native, an <a> stays a link, anything else gets role="button" and key handling. false forces button semantics on whatever renders (a link acting as a button).
className: string; A product's hook class for its own layout rules. Being retired: new code places an icon button with rootStyle; the call sites left are counted by ui.lint (kit-classname) and only go down.

Rest props go to <button> props.

Usage

Examples

Tooltips

Toggle

Busy, stop and send

Matrix

Customising

Accessibility

API reference

IconButton