Icon Button

Visual Hierarchy

Icon buttons are designed for secondary, toggleable actions. Use them alongside content (cards, list items) rather than as primary page actions. The particle animation rewards user interaction and provides clear feedback on state change.

Color Semantics

• Red [239, 68, 68] — Hearts, likes, favorites
• Yellow [234, 179, 8] — Stars, ratings, highlights
• Blue [59, 130, 246] — Shares, links, info actions
• Purple [147, 51, 234] — Bookmarks, saves, collections
• Coral [227, 103, 77] — Notifications, alerts (default)

Animation Considerations

Animations trigger only on activation (inactive → active), not deactivation. This creates a rewarding "pop" effect when users engage. For users who prefer reduced motion, set animate={false} or respect the prefers-reduced-motion media query.

Responsive Behavior

Use size="md" or size="lg" on touch devices for comfortable 44×44px minimum touch targets. The default 32px size works well for desktop hover-based interactions.

Keyboard Navigation

• Tab — Move focus to/from the button
• Enter or Space — Toggle the button state
• Focus ring uses the system ring color for consistency

Screen Reader Support

• Always provide aria-label — icon buttons have no visible text
• Use dynamic labels that reflect current state (e.g., "Unlike" vs "Like")
• Add aria-pressed={active} for toggle semantics
• Disabled state is announced automatically via the disabled attribute

Focus Management

Visible focus ring with 2px width using focus-visible:ring-2. The ring uses ring-ring color with offset for visibility against any background.

Motion Preferences

For users with vestibular disorders, disable animations via animate={false}. Consider checking window.matchMedia('(prefers-reduced-motion: reduce)') and passing the result to the animate prop.

ARIA Attributes

{/* Toggle button with dynamic label */}
<IconButton
  icon={Heart}
  active={isLiked}
  onClick={() => setIsLiked(!isLiked)}
  aria-label={isLiked ? "Unlike this item" : "Like this item"}
  aria-pressed={isLiked}
/>

{/* With description for screen readers */}
<div>
  <IconButton
    icon={Bell}
    active={notificationsOn}
    aria-describedby="notification-hint"
    aria-label="Toggle notifications"
    aria-pressed={notificationsOn}
  />
  <span id="notification-hint" className="sr-only">
    {notificationsOn
      ? "Notifications are currently enabled"
      : "Notifications are currently disabled"}
  </span>
</div>