Icon Button

Use icon buttons for compact, accessible icon-only interactions. Icon buttons are essential for space-efficient interfaces while maintaining accessibility compliance.

This is an enhanced version of the IconButton component from Radix Themes. For the original API reference, see the Radix Themes IconButton documentation.

Playground

Installation

npm install @kushagradhawan/kookie-ui

Usage

import { IconButton } from '@kushagradhawan/kookie-ui';
import { Settings } from 'lucide-react';
 
export function MyComponent() {
  return (
    <IconButton aria-label="Settings">
      <Settings />
    </IconButton>
  );
}

Props

Accessibility Requirements

Icon buttons must have an accessible name to meet WCAG guidelines. Provide accessibility through one of these methods:

aria-label

Direct descriptive text that explains the button's action.

import { Settings } from 'lucide-react';
 
<IconButton aria-label="Open settings">
  <Settings />
</IconButton>

aria-labelledby

Reference to a label element for more complex descriptions.

import { Settings } from 'lucide-react';
 
<IconButton aria-labelledby="settings-label">
  <Settings />
</IconButton>
<span id="settings-label">Open settings panel</span>

Visible Text Children

Fallback when visible text is included alongside the icon.

import { Settings } from 'lucide-react';
 
<IconButton>
  <Settings />
  Settings
</IconButton>

Variants

Use the variant prop to set button style.

Classic

Elevated style with subtle shadow for maximum visual impact.

import { Star } from 'lucide-react';
 
<IconButton size="3" variant="classic" aria-label="Favorite">
  <Star />
</IconButton>

Solid

Filled background for primary actions.

import { Plus } from 'lucide-react';
 
<IconButton size="3" variant="solid" aria-label="Add item">
  <Plus />
</IconButton>

Soft

Subtle background for secondary actions.

import { Edit } from 'lucide-react';
 
<IconButton size="3" variant="soft" aria-label="Edit">
  <Edit />
</IconButton>

Outline

Bordered style for secondary actions.

import { Copy } from 'lucide-react';
 
<IconButton size="3" variant="outline" aria-label="Copy">
  <Copy />
</IconButton>

Surface

Elevated surface for content-heavy UIs.

import { Share } from 'lucide-react';
 
<IconButton size="3" variant="surface" aria-label="Share">
  <Share />
</IconButton>

Ghost

Minimal style for utility actions.

import { X } from 'lucide-react';
 
<IconButton size="3" variant="ghost" aria-label="Close">
  <X />
</IconButton>

Sizes

Set size for button density. Icon buttons maintain square aspect ratios for consistent visual alignment.

Size 1

Compact for toolbars and dense interfaces.

import { ChevronDown } from 'lucide-react';
 
<IconButton size="1" aria-label="Expand">
  <ChevronDown />
</IconButton>

Size 2

Standard for most interface contexts.

import { ChevronDown } from 'lucide-react';
 
<IconButton size="2" aria-label="Expand">
  <ChevronDown />
</IconButton>

Size 3

Large for important actions and mobile touch targets.

import { ChevronDown } from 'lucide-react';
 
<IconButton size="3" aria-label="Expand">
  <ChevronDown />
</IconButton>

Size 4

Extra large for hero sections and maximum impact.

import { ChevronDown } from 'lucide-react';
 
<IconButton size="4" aria-label="Expand">
  <ChevronDown />
</IconButton>

Colors

Use the color prop with semantic colors to communicate action intent.

import { Heart, Trash, Check } from 'lucide-react';
 
<IconButton size="3" color="crimson" variant="solid" aria-label="Like">
  <Heart />
</IconButton>
<IconButton size="3" color="red" variant="soft" aria-label="Delete">
  <Trash />
</IconButton>
<IconButton size="3" color="green" variant="solid" aria-label="Confirm">
  <Check />
</IconButton>

Tooltips

Use the tooltip prop to add context to icon button actions. Always provide a tooltip for icon-only buttons to help users understand the action.

import { Save } from 'lucide-react';
 
<IconButton
  variant="soft"
  size="3"
  aria-label="Save"
  tooltip="Save your progress"
>
  <Save />
</IconButton>

Tooltip Position

Control tooltip placement with tooltipSide and tooltipAlign props.

import { Info } from 'lucide-react';
 
<IconButton
  aria-label="More information"
  tooltip="Click for details"
  tooltipSide="right"
  tooltipAlign="start"
>
  <Info />
</IconButton>

States

Loading

Set loading to show a spinner and disable the button.

import { Upload } from 'lucide-react';
 
<IconButton size="3" aria-label="Upload" loading>
  <Upload />
</IconButton>

Disabled

Set disabled to prevent interaction.

import { Send } from 'lucide-react';
 
<IconButton size="3" aria-label="Send" disabled>
  <Send />
</IconButton>

Polymorphism

As

Use the as prop to render as different HTML elements while maintaining icon button styling.

import { ExternalLink } from 'lucide-react';
 
<IconButton size="3" as="a" href="/home" aria-label="Go home">
  <ExternalLink />
</IconButton>

AsChild

Use the asChild prop to merge props with a child element using the Radix Slot pattern.

import { ArrowRight } from 'lucide-react';
 
<IconButton size="3" asChild aria-label="Go to dashboard">
  <a href="/dashboard">
    <ArrowRight />
  </a>
</IconButton>

Responsive

Use responsive objects with the size prop to adapt sizing across breakpoints.

import { Menu } from 'lucide-react';
 
<IconButton size={{ initial: '2', sm: '3', md: '4' }} aria-label="Menu">
  <Menu />
</IconButton>

Accessibility

Kookie UI's IconButton enforces accessibility requirements with runtime validation.

Enforced Accessible Name

IconButton throws an error in development if no accessible name is provided. This ensures WCAG compliance and catches accessibility issues early.

Keyboard Navigation

• Full keyboard support with Enter and Space keys
• Visible focus indicators for all variants
• Enhanced focus management for Windows High Contrast mode

Screen Readers

• Semantic button elements with proper roles
• Loading state announcements
• Tooltip associations via aria-describedby
• Disabled state announcements

Enhancements

Kookie UI extends Radix Themes IconButton with practical improvements:

Built-in Tooltip Support

Native tooltip prop eliminates need for wrapper components. Tooltips automatically provide accessibility through aria-describedby associations.

Runtime Accessibility Validation

Enforced accessibility requirements with helpful error messages in development. Ensures all icon buttons have proper accessible names.

Enhanced Loading State

Loading state automatically disables interaction and displays spinner with proper accessibility announcements.

Changelog

Added

• Built-in tooltip support through tooltip, tooltipSide, tooltipAlign props
• Runtime accessibility validation for missing accessible names
• New material prop for solid/translucent theme contexts
• Enhanced form integration with complete HTML form attribute support

Changed

• Improved 3D shadow system for classic variant
• Better contrast relationships in both light and dark themes

Removed

• highContrast prop. Gray fills with step 12 on its own, and icons read the strong ink by default.

Fixed

• Better color saturation and brightness in high contrast mode
• Enhanced focus indicators for improved accessibility