Icon Button
A button with an icon instead of a label, for toolbars and repeated actions. It shares Button's styles, sizes and states, and always carries a written name for screen readers.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add icon-buttonAlso works with shadcn:
npx shadcn@latest add @ritla/icon-buttonDependencies it brings
@base-ui/react@phosphor-icons/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { MagnifyingGlassIcon } from "@phosphor-icons/react/ssr";import { IconButton } from "@/components/ui/icon-button";<IconButton variant="outline" icon={MagnifyingGlassIcon} label="Search" />Examples
Sizes
Each size is a square as tall as the Button of the same size (56, 48, 40 and 32px), so the two line up in a row. The tap target stays at least 48px at sm and xs.
Styles
Button's five styles with the same colors; the icon takes the label color. danger turns any style red, and inverted-ghost goes on colored surfaces.
Shape
square (default) takes the Button radius for its size; round is fully round, for floating actions and next to avatars.
States
loading puts the spinner in place of the icon and keeps focus and the name; disabled switches it off. Press Save, and change the label while loading (“Saving”).
Toolbar in Arabic
Back uses ArrowLeftIcon in both languages and points right in Arabic, because back runs against the reading direction. Search, notifications and the menu never mirror; the row follows the page direction.
Close button
The close button sits at the inline end, the left in Arabic. xs suits dense headers and stays easy to hit.
When to use a labeled Button
Icon buttons are for familiar icons (edit, share, search). A destructive action needs words, so use a labeled Button rather than a lone trash icon, and don't put two filled icon buttons side by side.
API reference
IconButton
Any other Base UI Button prop passes through (onClick, type…).
| Prop | Type | Default | Description |
|---|---|---|---|
icon | IconComponent | None | Figma's Change icon: a Phosphor or Ritla UI icon. Directional icons mirror in Arabic on their own. |
label | string | None | Required. The name screen readers announce (aria-label), in the page language. |
shape | "square" | "round" | "square" | Figma's Shape: the Button radius, or a full circle. |
variant | "filled" | "tonal" | "outline" | "ghost" | "inverted-ghost" | "filled" | Figma's Style, as on Button. |
size | "lg" | "md" | "sm" | "xs" | "lg" | Figma's Size: a 56, 48, 40 or 32px square. |
danger | boolean | false | Figma's Danger: red, with a red focus ring. |
loading | boolean | false | State = Loading: the spinner replaces the icon, aria-busy, and the button stays focusable. |
disabled | boolean | false | State = Disabled. |
render | ReactElement | None | Another element with the Icon Button look, usually a link. It keeps its semantics and takes label as its name. |
className | string | None | Extra classes merged with cn(). |
Anatomy
The parts of an icon button and where each one lives in Figma and in code.
- 1. Touch target
size/touch-targetAt least 48 px in every size.smandxsadd an invisible 48 px square without taking layout space. - 2. Content
sizeA square box per Size:lg56,md48,sm40,xs32, with the Button radius for its size. - 3. Icon
iconThe Icon swap (Phosphor), 24 atlg, 20 atmd,smandxs; takes the label colour. Directional icons mirror in Arabic. - 4. Label (not drawn)
labelA hidden text property, required. It becomesaria-labeland the icon isaria-hidden. - 5. Shape
shapesquare(the default) orround, which swaps the radius forradius/full. - 6. Danger
dangerThe red palette and a red focus ring. - 7. Spinner
loadingState=Loading: the spinner replaces the icon.aria-busy; the button stays focusable.
Usage guidelines
An icon button stands in for a familiar action with an icon. Which icons to use, how to name the button, and the checks before handoff.
1. Pick familiar icons
An icon button only works when everyone reads the icon the same way: back, search, notifications, edit, share, download, close.
A document toolbar
Three actions above a document.
Do
- Use an icon button only when the icon is unmistakable: close, search, more, edit.
Don't
- Rely on a custom icon the person has never seen.
2. Name every icon button
label is required in code, so an icon button never ships without a name; it becomes aria-label and the icon is hidden from screen readers. In Figma, fill the hidden Label property so Dev Mode shows the name. Name the action, not the icon (Close, not X), in the page language.
Do
- Give every icon button an accessible name, and a tooltip in toolbars.
3. One filled at a time
filled marks the main action. Next to other icon buttons, keep it to one.
A list row with actions
Edit, share and add on one row.
filled, the rest ghostThe main action stands out and the others stay quiet.filled side by sideTwo equal weights make people stop and compare.Don't
- Use an icon button for the main action of a screen; use a labeled Button.
4. Destructive actions need words
A trash icon alone is easy to press by mistake and easy to misread.
Deleting a project
The last action on a settings page.
dangerThe words say exactly what will be deleted.5. Match the size of the row
Each icon button is as tall as the Button of the same size, so pick the same size for both.
A save bar
A menu icon button next to Save.
md next to mdEdges line up and the row reads as one group.lg next to smMixed heights look broken and shift the baseline.6. Loading and disabled
Loading: the spinner replaces the icon, the button keeps focus and its name, and presses are ignored; change the label to its in-progress form (Saving). Disabled: use it sparingly and say nearby why the action is not available.
7. Arabic and RTL
Back points right in Arabic. Pick the ArrowLeft icon: it mirrors on its own.
An Arabic page header
Back and search, right to left.
Before handoff
- Every instance has its Label filled in the page language.
- Icons are familiar, and directional ones use RTL = Yes in Arabic frames.
- One
filledper group. - Sizes match the Buttons in the same row.
- Destructive actions are labeled Buttons.
Tokens & specs
Every value on Icon Button is a variable, the same ones as Button. These are the ones bound on the component, by size and by style.
Sizes
Box, inner padding and radius of the Content frame, with the icon size. Every size sits in a touch target of size/touch-target (48); sm and xs add it without taking layout space.
| Size | Box, padding, radius | Icon |
|---|---|---|
lg | 56 · space-16 · radius/10 | 24 |
md | 48 · space-14 · radius/8 | 20 |
sm | 40 · space-10 · radius/6 | 20 |
xs | 32 · space-6 · radius/4 | 20 |
shape="round" | radius/full | 24 · 20 |
Colors
Fill, border and icon colour per style in the Enabled state, the same variables as Button. Light and dark come from the 1. Colors mode, not from separate variants.
| Style | Fill and border | Icon |
|---|---|---|
filled | background/brand/solid | text/brand/on-brand |
filled · danger | background/danger/solid | text/static/white |
tonal | background/brand/faint | text/brand/subtle |
tonal · danger | background/danger/faint | text/danger/subtle |
outline | background/surface/lowest · border/gray/soft | text/gray/subtle |
outline · danger | background/surface/lowest · border/danger/soft | text/danger/subtle |
ghost | alpha/tint-12 | text/gray/subtle |
ghost · danger | alpha/tint-12 | text/danger/subtle |
inverted-ghost | alpha/tint-12 | text/static/white |
Focus
State=Focused draws the Focus/focus-ring effect style (effects/focus/main) with border-width/thicker; with danger the ring is red. In code it is automatic on :focus-visible.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| Tab | Moves focus to the button and shows the focus ring (red with danger). |
| EnterSpace | Activates it. While loading, focus stays and the action doesn't repeat. |
ARIA
labelis required by the type, so an icon button can't ship without a name. It becomesaria-label; the icon isaria-hidden.- Write the name in the page language (“بحث”, not “Search”, in Arabic), and name the action, not the icon (“Close”, not “X”).
- Loading sets
aria-busy="true"andaria-disabled="true"instead ofdisabled, so focus isn't lost. - The tap target is at least 48px at every size (WCAG 2.5.8), even when the button is drawn at 32px.
- In toolbars, sighted users need a tooltip too. It comes with the Tooltip component.
Do
- Keep the hit area at least 48 px at every size, even
xs. - Tab moves focus and shows the ring (red with
danger); Enter and Space activate. - While loading, use
aria-busyandaria-disabledinstead ofdisabledso focus is not lost, which code does for you. - In toolbars, add a tooltip for sighted users too.
Arabic and RTL notes
Mirrors
- Arrows and carets flip through
<Icon>: Back withArrowLeftIconpoints right in Arabic. - Toolbar order mirrors with the page, and the close button stays at the inline end.
Does not mirror
- The button itself never mirrors and has no RTL prop; only the icon decides.
- Search, notifications, the menu, heart, download and the loading spinner stay the same in both languages.
- Numerals
- An icon button has no numerals. If you add a count badge over it, format it with
formatNumberso it follows the numerals setting. - Arabic typography
- No visible text; the name lives in
label. Write it in natural Arabic: a screen reader speaks it with an Arabic voice when the page islang="ar". - Mixed-direction text
- A Latin brand inside an Arabic
label(“مشاركة عبر WhatsApp”) reads correctly without<bdi>:aria-labelis spoken, not displayed.
Do
- Use the
ArrowLefticon for Back: it points right in Arabic. - In Arabic Figma frames, use RTL = Yes for directional icons.
Don't
- Mirror icons that are not directional: search, settings, more.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space