Fair Case

IconButton

A round icon-only button. Its label is both the accessible name and a tooltip on hover and keyboard focus. A disabled one stays focusable so the tooltip can still say why.

Variants

Ghost, control, signal and active. The second ghost button has its hover fill drawn on it.

ghost
ghost, hover
control
signal
active, sm

TSX

// IconButton: a round button with only an icon. label is required: it is the
// accessible name and the tooltip on hover and keyboard focus. The variants
// set the fill: ghost (the default) has none, control has the control fill,
// signal the signal fill, and active the accent fill. Set tooltip={false}
// when the name is already visible or the button sits in a dense row.
import { IconButton } from "@repo/ui/icon-button";
import { CloseIcon, MenuIcon, SearchIcon, UploadIcon } from "@repo/ui/icons";

export default function IconButtonVariants() {
  return (
    <>
      <IconButton label="Search">
        <SearchIcon />
      </IconButton>
      <IconButton label="Open menu" variant="control">
        <MenuIcon />
      </IconButton>
      <IconButton label="Upload a file" variant="signal">
        <UploadIcon />
      </IconButton>
      <IconButton label="Close" variant="active" size="sm">
        <CloseIcon />
      </IconButton>
    </>
  );
}

Sizes

Six sizes. 2xs is drawn at 28px with a 44px touch area, shown dashed. responsive is 44px below 768px and 32px from 768px, so it changes as you resize.

md · 44
sm · 40
xs · 32
2xs · 28, 44 touch area
3xs · 24
responsive · 44, then 32

TSX

// IconButton's six sizes: md 44px (the default), sm 40, xs 32, 2xs 28, 3xs 24
// and responsive. Use 2xs where a 28px control must still be tappable: it
// adds an invisible 44px touch area. responsive is 44px below 768px and 32px
// from 768px, for a control in a phone's thumb reach. The smallest two take
// smaller icons.
import { IconButton } from "@repo/ui/icon-button";
import { CloseIcon, MenuIcon, SearchIcon } from "@repo/ui/icons";

export default function IconButtonSizes() {
  return (
    <>
      <IconButton label="Search" variant="control" size="md">
        <SearchIcon />
      </IconButton>
      <IconButton label="Search" variant="control" size="sm">
        <SearchIcon />
      </IconButton>
      <IconButton label="Search" variant="control" size="xs">
        <SearchIcon />
      </IconButton>
      <IconButton label="Clear" variant="control" size="2xs">
        <CloseIcon size="sm" />
      </IconButton>
      <IconButton label="Remove" variant="control" size="3xs">
        <CloseIcon size="xs" />
      </IconButton>
      <IconButton label="Pause" variant="control" size="responsive">
        <MenuIcon />
      </IconButton>
    </>
  );
}

Disabled with a hint

Dimmed to 40%, but it keeps focus so its tooltip can say why. The tooltip is the inverse pill, 8px from the button.

Add a message first
The hint, drawn open. On the site it opens on hover and keyboard focus.

TSX

// A disabled IconButton with a hint: it dims to 40% but stays focusable, so
// its tooltip can say why it is off. hint replaces the label in the tooltip;
// the label stays the accessible name. TooltipProvider gives the tooltips in a
// region one shared open delay.
//
// The docs page draws this tooltip open as a still, since it opens on hover
// and focus, which needs script. In the app it is this code as written.
import { IconButton, TooltipProvider } from "@repo/ui/icon-button";
import { UploadIcon } from "@repo/ui/icons";

export default function IconButtonHint() {
  return (
    <TooltipProvider>
      <IconButton
        label="Upload a file"
        hint="Add a message first"
        variant="control"
        disabled
      >
        <UploadIcon />
      </IconButton>
    </TooltipProvider>
  );
}

Code

TSX

// IconButton in use: a region of icon buttons under one TooltipProvider, so
// their tooltips share an open delay. Without label there is no accessible
// name. A page that must draw the button before its script arrives puts
// iconButtonVariants (from @repo/ui/icon-button-variants) on a plain <button>.
import { IconButton, TooltipProvider } from "@repo/ui/icon-button";
import { MenuIcon, UploadIcon } from "@repo/ui/icons";

export default function IconButtonUsage() {
  return (
    <TooltipProvider>
      <IconButton
        label="Upload a file"
        hint="Add a message first"
        variant="control"
        disabled
      >
        <UploadIcon />
      </IconButton>
      <IconButton label="Open menu" variant="control">
        <MenuIcon />
      </IconButton>
    </TooltipProvider>
  );
}

Without the label there is no accessible name. A page that draws one before the code arrives uses iconButtonVariants from @repo/ui/icon-button-variants on a plain <button> (header-popup-triggers.tsx).

Variants

Variants
PropValueHow it looks
variantghostNo fill, text colour (#00172E light, #FAFDFF dark). Hover fill: tint (#EEF6FF light, #122A43 dark) or, with fill track, the track tone (ink 14% light, ground 18% dark).
variantsignalSignal fill (#0D84FF light, #7EB7FF dark), glyph in on-signal (#FAFDFF light, #00172E dark). Hover: accent-hover fill (#143D8D light, #B2D5FF dark).
variantactiveAccent fill (#0E6FD6 light, #7EB7FF dark), glyph in on-accent (#FAFDFF light, #00172E dark). No hover rule of its own.
variantcontrolControl fill (ink 6% light, ground 8% dark), text colour. Hover: track tone (ink 14% light, ground 18% dark).
sizemd44px circle. The default.
sizesm40px circle.
sizexs32px circle.
size2xsDrawn at 28px with an invisible 44px touch area (8px added on every side).
size3xs24px circle, the smallest target WCAG 2.5.8 allows.
sizeresponsive44px below 768px, 32px from 768px, for a control in a phone's thumb reach.
fillhoverGhost hover tone is the tint fill. The default.
filltrackGhost hover tone is the track fill, as the composer's chips use (spec 3.8).
tooltippopupInverse pill: text-colour fill, page-colour text, 14px weight 500, 10px side and 6px vertical padding, rounded-8, 8px from the button, fades over 150ms.

States

States
StateHow it looks
restAs the variant describes. Round (rounded-full), glyph centred.
hoverghost and control take their hover fill, signal takes accent-hover. Eases over 300ms. Not applied while disabled.
focusKeyboard focus draws the 2px focus ring with a 2px gap and shows the tooltip.
disabledOpacity 40%, not-allowed cursor, no hover, still focusable. The tooltip shows hint (or the label).
pressednot written for the button itself. A caller can set aria-pressed (the voice button does) and switch variant to active.
opennot written

Props

Import from @repo/ui/icon-button.

Props
PropTypeDefaultWhat it does
labelstringdefault requiredThe accessible name (aria-label) and the tooltip text.
hintstring | undefinedTooltip text when it differs from the name, such as why it is disabled.
childrenReactNodedefault requiredThe icon.
variant"ghost" | "signal" | "active" | "control"default "ghost"The fill and colour.
size"md" | "sm" | "xs" | "2xs" | "3xs" | "responsive"default "md"The drawn size.
fill"hover" | "track"default "hover"A ghost button's hover tone. track is for the composer's controls. The other variants keep their own.
tooltipbooleandefault trueSet false to draw no tooltip, for example when the name is already visible beside it.
disabledbooleanDims to 40% and blocks the cursor, but the button stays focusable (aria-disabled) so the tooltip can explain.
classNamestringExtra classes, merged with cn().
...restBase UI Button props minus className, children, aria-labeltype, onClick, aria-pressed and so on.
TooltipProviderTooltip.ProviderWraps a page or region so its tooltips share one open delay.

Use it well

  • Always give a label. It is the accessible name and the tooltip.

  • Set tooltip={false} when the name is already visible or the control sits in a dense row (a staged file's remove button, the voice cancel button).

  • A disabled button stays focusable on purpose, so give it a hint that says why.

  • Use size 2xs where a 28px control must still be tappable: it adds a 44px touch area.

  • Use iconButtonVariants on a plain element when a page must draw the button before Base UI loads (the site header's menu button).

  • Wrap the region in TooltipProvider so the tooltips share one open delay (the hero does).