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.
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.
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.
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
| Prop | Value | How it looks |
|---|---|---|
| variant | ghost | No 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). |
| variant | signal | Signal fill (#0D84FF light, #7EB7FF dark), glyph in on-signal (#FAFDFF light, #00172E dark). Hover: accent-hover fill (#143D8D light, #B2D5FF dark). |
| variant | active | Accent fill (#0E6FD6 light, #7EB7FF dark), glyph in on-accent (#FAFDFF light, #00172E dark). No hover rule of its own. |
| variant | control | Control fill (ink 6% light, ground 8% dark), text colour. Hover: track tone (ink 14% light, ground 18% dark). |
| size | md | 44px circle. The default. |
| size | sm | 40px circle. |
| size | xs | 32px circle. |
| size | 2xs | Drawn at 28px with an invisible 44px touch area (8px added on every side). |
| size | 3xs | 24px circle, the smallest target WCAG 2.5.8 allows. |
| size | responsive | 44px below 768px, 32px from 768px, for a control in a phone's thumb reach. |
| fill | hover | Ghost hover tone is the tint fill. The default. |
| fill | track | Ghost hover tone is the track fill, as the composer's chips use (spec 3.8). |
| tooltip | popup | Inverse 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
| State | How it looks |
|---|---|
| rest | As the variant describes. Round (rounded-full), glyph centred. |
| hover | ghost and control take their hover fill, signal takes accent-hover. Eases over 300ms. Not applied while disabled. |
| focus | Keyboard focus draws the 2px focus ring with a 2px gap and shows the tooltip. |
| disabled | Opacity 40%, not-allowed cursor, no hover, still focusable. The tooltip shows hint (or the label). |
| pressed | not written for the button itself. A caller can set aria-pressed (the voice button does) and switch variant to active. |
| open | not written |
Props
Import from @repo/ui/icon-button.
| Prop | Type | Default | What it does |
|---|---|---|---|
| label | string | default required | The accessible name (aria-label) and the tooltip text. |
| hint | string | undefined | Tooltip text when it differs from the name, such as why it is disabled. | |
| children | ReactNode | default required | The 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. |
| tooltip | boolean | default true | Set false to draw no tooltip, for example when the name is already visible beside it. |
| disabled | boolean | Dims to 40% and blocks the cursor, but the button stays focusable (aria-disabled) so the tooltip can explain. | |
| className | string | Extra classes, merged with cn(). | |
| ...rest | Base UI Button props minus className, children, aria-label | type, onClick, aria-pressed and so on. | |
| TooltipProvider | Tooltip.Provider | Wraps 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).