Skip to content

Icon Button

Get Ritla UI

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

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add icon-button

    Also works with shadcn: npx shadcn@latest add @ritla/icon-button

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/react

  3. Or 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

icon-button.tsx
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.

EnglishMirroredArabic
LTR →

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.

EnglishMirroredArabic
LTR →

Shape

square (default) takes the Button radius for its size; round is fully round, for floating actions and next to avatars.

EnglishMirroredArabic
LTR →

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”).

EnglishMirroredArabic
LTR →

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.

EnglishMirroredArabic
LTR →

Close button

The close button sits at the inline end, the left in Arabic. xs suits dense headers and stays easy to hit.

EnglishMirroredArabic
LTR →

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.

EnglishMirroredArabic
LTR →

API reference

IconButton

Any other Base UI Button prop passes through (onClick, type…).

PropTypeDefaultDescription
iconIconComponentNoneFigma's Change icon: a Phosphor or Ritla UI icon. Directional icons mirror in Arabic on their own.
labelstringNoneRequired. 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.
dangerbooleanfalseFigma's Danger: red, with a red focus ring.
loadingbooleanfalseState = Loading: the spinner replaces the icon, aria-busy, and the button stays focusable.
disabledbooleanfalseState = Disabled.
renderReactElementNoneAnother element with the Icon Button look, usually a link. It keeps its semantics and takes label as its name.
classNamestringNoneExtra classes merged with cn().

Anatomy

The parts of an icon button and where each one lives in Figma and in code.

  1. 1. Touch targetsize/touch-targetAt least 48 px in every size. sm and xs add an invisible 48 px square without taking layout space.
  2. 2. ContentsizeA square box per Size: lg 56, md 48, sm 40, xs 32, with the Button radius for its size.
  3. 3. IconiconThe Icon swap (Phosphor), 24 at lg, 20 at md, sm and xs; takes the label colour. Directional icons mirror in Arabic.
  4. 4. Label (not drawn)labelA hidden text property, required. It becomes aria-label and the icon is aria-hidden.
  5. 5. Shapeshapesquare (the default) or round, which swaps the radius for radius/full.
  6. 6. DangerdangerThe red palette and a red focus ring.
  7. 7. SpinnerloadingState=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: Familiar iconsEdit, share and download read the same for everyone.
Don't: An icon that guessesA gear for Export makes people guess. Use a labeled Button when no icon fits.

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.

Do: One filled, the rest ghostThe main action stands out and the others stay quiet.
Don't: Two 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.

Do: Labeled Button with dangerThe words say exactly what will be deleted.
Don't: A lone red trash iconRed draws the eye but does not say what goes.

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.

Do: md next to mdEdges line up and the row reads as one group.
Don't: 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.

Do: Back points rightIt points toward where the reader came from.
Don't: Back points leftIn Arabic that reads as forward.

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 filled per 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.

SizeBox, padding, radiusIcon
lg56 · space-16 · radius/1024
md48 · space-14 · radius/820
sm40 · space-10 · radius/620
xs32 · space-6 · radius/420
shape="round"radius/full24 · 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.

StyleFill and borderIcon
filledbackground/brand/solidtext/brand/on-brand
filled · dangerbackground/danger/solidtext/static/white
tonalbackground/brand/fainttext/brand/subtle
tonal · dangerbackground/danger/fainttext/danger/subtle
outlinebackground/surface/lowest · border/gray/softtext/gray/subtle
outline · dangerbackground/surface/lowest · border/danger/softtext/danger/subtle
ghostalpha/tint-12text/gray/subtle
ghost · dangeralpha/tint-12text/danger/subtle
inverted-ghostalpha/tint-12text/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.

KeyAction
TabMoves focus to the button and shows the focus ring (red with danger).
EnterSpaceActivates it. While loading, focus stays and the action doesn't repeat.

ARIA

  • label is required by the type, so an icon button can't ship without a name. It becomes aria-label; the icon is aria-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" and aria-disabled="true" instead of disabled, 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-busy and aria-disabled instead of disabled so 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 with ArrowLeftIcon points 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 formatNumber so 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 is lang="ar".
Mixed-direction text
A Latin brand inside an Arabic label (“مشاركة عبر WhatsApp”) reads correctly without <bdi>: aria-label is spoken, not displayed.

Do

  • Use the ArrowLeft icon 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.

  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space