Icon Button

Common Icon Button Variants

Size Variants

Shape Variants

Icon Button Properties

Important: aria-label is not optional. Without it, screen readers announce the button as "button" with no context. The label should describe the action, not the icon: "Delete message" not "Trash can". See the Button component for additional shared button props.

Design Token Mappings

The ghost/standard variant's hover background is critical: it must be subtle enough not to compete with the icon but visible enough to signal interactivity. An alpha-based color (rgba(0,0,0,0.04)) works across light/dark themes better than a hardcoded gray.

Icon Button States

Toggle Icon Button States (e.g., Favorite)

Accessibility

Icon buttons are among the most frequently inaccessible components in the wild. The absence of visible text makes proper ARIA labeling absolutely critical.

Accessible Name (WCAG 4.1.2 – Name, Role, Value):

• Every icon button MUST have aria-label or aria-labelledby providing a clear action description
• The label should describe the action, not the icon: "Close dialog" not "X", "Delete message" not "Trash"
• For toggle buttons, the label should reflect the current or target state: "Add to favorites" (when unfavorited), or use aria-pressed with a static label "Favorite"
• Don't use title as the only accessible name — its behavior is inconsistent across screen readers

Role and State (WCAG 4.1.2):

• Standard icon buttons: native <button> element is sufficient — no additional role needed
• Toggle icon buttons: add aria-pressed="true|false" to communicate the toggled state
• Don't use <div> or <span> with click handlers — always use <button> or <a> (if navigation)

Target Size (WCAG 2.5.8 – Target Size Minimum, 2.5.5 – Target Size Enhanced):

• WCAG 2.2 Level AA requires 24×24 CSS pixels minimum (SC 2.5.8)
• Level AAA requires 44×44 CSS pixels (SC 2.5.5)
• Small icon buttons (32px or less) should have padding or margin to ensure the tap target reaches at least 44px on touch devices
• In dense toolbars, ensure at least 8px spacing between adjacent icon buttons

Color Contrast (WCAG 1.4.3, 1.4.11):

• Icon color must achieve 3:1 against the button background (WCAG 1.4.11 – Non-text Contrast) — icons are graphical objects
• On hover, the icon must still maintain contrast against the hover background
• For filled variant: icon-on-fill must achieve 3:1 minimum. Use the Contrast Checker.

Keyboard (WCAG 2.1.1):

• Must be focusable and activatable with Enter/Space
• In toolbars (role="toolbar"), arrow keys navigate between buttons, Tab enters/exits the toolbar
• Focus ring must be visible and not clipped by border-radius: 50% — use outline-offset

Tooltips (WCAG 1.3.1, Content on Hover 1.4.13):

• Tooltips on icon buttons should show the action label on hover and keyboard focus
• Tooltip must be dismissible (Escape), hoverable (mouse can enter tooltip), and persistent (doesn't disappear while hovering)
• See Tooltip component for full requirements

Usage Guidelines

Do:

• Always provide aria-label — this is the #1 rule for icon buttons
• Add a Tooltip for any icon that's not universally recognized
• Use universally understood icons: ✕ (close), ← (back), ☰ (menu), 🔍 (search), ⚙ (settings), ❤ (favorite), 🗑 (delete)
• Maintain minimum 44px touch targets on mobile — pad small buttons with invisible touch areas
• Use consistent icon sizes within the same toolbar or context
• Pair with the Button component for primary actions that need text labels

Don't:

• Don't use icon buttons without aria-label — an icon without a name is invisible to screen readers
• Don't use ambiguous icons without tooltips — a pencil icon means "edit" in one context and "draw" in another
• Don't mix icon button sizes within the same toolbar
• Don't use icon buttons for destructive actions without confirmation — accidental clicks are more likely on small targets
• Don't use custom/novel icons for critical actions — stick to established iconography
• Don't put text inside an icon button — that's a regular button. Use Button.

Design System Implementations

Material Design (MUI) provides <IconButton> with size (small, medium, large), color (default, inherit, primary, secondary, error, info, success, warning), and edge (start, end, false) for alignment in list items and toolbars. MUI's IconButton renders a <button> with a circular ripple effect. The edge prop adjusts negative margin to align the icon with content edges. MUI v5 added disableRipple for accessibility concerns with the ripple animation. Icon size is controlled by wrapping the icon in MUI's <SvgIcon> with fontSize prop.

Ant Design does not have a dedicated IconButton. Instead, Ant's <Button> with type="text", shape="circle", and icon={<IconComponent />} creates the equivalent. Ant's icon system (@ant-design/icons) provides consistent 14px/16px/20px icon sizes. For toolbar-style icon buttons, Ant recommends <Space.Compact> wrapping <Button shape="circle"> elements.

Chakra UI provides <IconButton> with icon, aria-label (required), variant (solid, outline, ghost, link), size, colorScheme, and isRound props. Chakra enforces aria-label as a required prop at the TypeScript level — builds fail without it. The isRound prop toggles between circular and rounded-square shapes.

Bootstrap uses .btn with no text content, just an icon element inside. There is no dedicated IconButton class. Teams typically add custom CSS for consistent square sizing: .btn-icon { width: 40px; height: 40px; padding: 0; display: inline-flex; align-items: center; justify-content: center; }. Bootstrap Icons (bootstrap-icons) provides the icon library.

Apple Human Interface Guidelines treats icon-only buttons as standard buttons with SF Symbols icons. In SwiftUI, Button(action: {}) { Image(systemName: "heart") }.buttonStyle(.plain) creates an icon button. Apple requires all icon buttons to have accessibility labels: .accessibilityLabel("Add to favorites"). Apple recommends a minimum 44×44pt touch target for all interactive elements — enforced by Accessibility Inspector. See the Button component for Apple's broader button guidance.

Tailwind CSS icon buttons are composed with utilities: inline-flex items-center justify-center w-10 h-10 rounded-full hover:bg-gray-100 transition-colors. The group class enables hover-triggered tooltip display. Headless UI's <Button> and Radix's <ToggleButton> provide the behavioral primitives. Icon sizing typically uses Heroicons (24px) or Lucide (24px default, configurable).