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" />} />.

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 the glyph's filled form, and sets aria-pressed. An open popup lights the trigger but never fills its glyph.

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" />

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} />

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

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.

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).
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: booleanDefaultfalse; 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.
filled: boolean; Draw the glyph's filled form. Default: while pressed (a toggle that is on); an open popup never fills it.
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