Icon Button
Icon buttons are compact buttons that display only an icon. They are used for secondary actions and toolbar controls where space is limited.
Variants
Sizes
States
Props
| Name | Type | Default | Description |
|---|---|---|---|
variant | 'primary' | 'secondary' | 'tertiary' | 'error' | 'primary' | Visual style variant of the icon button |
size | 'sm' | 'md' | 'lg' | 'md' | Size of the icon button |
disabled | boolean | - | Whether the button is disabled |
aria-label* | string | - | Accessible label for screen readers (required for accessibility) |
children* | React.ReactNode | - | Icon element (usually from lucide-react) |
onClick | () => void | - | Click event handler |
Usage Guidelines
When to use
- •For toolbars and compact action bars
- •For secondary actions next to primary content
- •When space is limited and the icon meaning is clear
- •For repeated actions in lists or tables
Best practices
- •Always provide an aria-label for accessibility
- •Use widely recognized icons (search, close, delete, etc.)
- •Match icon size to button size (sm: h-4, md: h-5, lg: h-6)
- •Consider adding a tooltip for less common icons
- •Use consistent icon style throughout the application
Accessibility
- •aria-label is required for screen readers to describe the action
- •All icon buttons have proper focus states for keyboard navigation
- •Disabled buttons are marked with aria-disabled
- •The icon should be clearly recognizable and not ambiguous
Do's and Don'ts
✓ Do
- •Use widely recognized icons that users will understand instantly
- •Always provide descriptive aria-label attributes
- •Add tooltips for icon buttons to improve discoverability
- •Use consistent icon sizes within the same context
- •Use error variant for destructive actions like delete
✗ Don't
- •Don't use obscure icons that require explanation
- •Don't omit aria-label - it's required for accessibility
- •Don't mix icon sizes randomly in toolbars
- •Don't use icon buttons for primary page actions
- •Don't use icons that look similar for different actions
Related Components
Button
Full button with text label
Button Group
Group related buttons together
Tooltip
Add helpful hints to icon buttons