@bttrlabs/icons

Unified icon system for the Bttr Design System, built on Lucide React with automatic dark theme support.

Features

• ✨ 1450+ Icons: Complete Lucide icon library with tree-shaking support
• 🌓 Dark Theme Support: Icons automatically adapt to theme using currentColor
• 📏 Size Presets: Convenient size shortcuts (sm, md, lg, xl) or custom pixel values
• 🎨 Type-Safe: Full TypeScript support with autocomplete for all icon names
• 🧩 Icon Categories: Organized collections for easy discovery
• 🔘 IconButton: Ready-to-use button component with variants and states
• ♿ Accessible: Built-in ARIA support and semantic HTML

Installation

pnpm add @bttrlabs/icons

Usage

Basic Icon

import { Icon } from '@bttrlabs/icons';

function MyComponent() {
  return <Icon name="Mail" size="md" />;
}

With Custom Color

<Icon name="Heart" size="lg" color="#EF4444" />

Icon Sizes

// Using presets
<Icon name="Settings" size="sm" />  {/* 16px */}
<Icon name="Settings" size="md" />  {/* 20px - default */}
<Icon name="Settings" size="lg" />  {/* 24px */}
<Icon name="Settings" size="xl" />  {/* 32px */}

// Custom size
<Icon name="Settings" size={48} />

IconButton Component

import { IconButton } from '@bttrlabs/icons';

// Basic usage
<IconButton
  icon="Settings"
  ariaLabel="Open settings"
/>

// With variants
<IconButton
  icon="Trash2"
  variant="outline"
  colorScheme="danger"
  ariaLabel="Delete item"
/>

// Loading state
<IconButton
  icon="Save"
  loading={true}
  ariaLabel="Saving..."
/>

// With tooltip
<IconButton
  icon="Info"
  tooltip="More information"
  ariaLabel="More information"
/>

IconButton Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | icon | keyof typeof icons | - | Icon name (required) | | variant | 'ghost' \| 'outline' \| 'solid' | 'ghost' | Visual style variant | | size | 'sm' \| 'md' \| 'lg' | 'md' | Button size | | colorScheme | 'default' \| 'accent' \| 'danger' \| 'success' | 'default' | Color scheme | | ariaLabel | string | - | Accessible label (required) | | tooltip | string | - | Tooltip text on hover | | loading | boolean | false | Show loading spinner | | disabled | boolean | false | Disable the button |

Direct Icon Imports

You can also import Lucide icons directly:

import { Mail, Settings, User } from '@bttrlabs/icons';

function MyComponent() {
  return (
    <div>
      <Mail size={24} />
      <Settings size={24} />
      <User size={24} />
    </div>
  );
}

Icon Categories

Discover icons organized by category:

import {
  navigationIcons,
  actionIcons,
  statusIcons,
  themeIcons
} from '@bttr/icons';

// navigationIcons includes: ArrowLeft, ArrowRight, ChevronLeft, Home, Menu, etc.
// actionIcons includes: Edit, Trash2, Plus, Save, Copy, Download, etc.
// statusIcons includes: CheckCircle, AlertCircle, Info, Loader, etc.
// themeIcons includes: Sun, Moon, Monitor

Available categories:

• navigationIcons - Navigation and directional icons
• actionIcons - Common action icons (edit, delete, add, etc.)
• communicationIcons - Mail, messaging, phone icons
• mediaIcons - File, image, video, folder icons
• interfaceIcons - Settings, search, filter, UI controls
• statusIcons - Success, error, warning, info indicators
• dataIcons - Charts, graphs, analytics icons
• commerceIcons - Shopping, payment icons
• formIcons - Calendar, user, authentication icons
• themeIcons - Theme switching icons (sun, moon, monitor)
• socialIcons - Social media platform icons

Dark Theme Support

Icons use currentColor by default, which means they automatically inherit the text color from their parent element. This allows them to seamlessly adapt to light and dark themes:

// Light theme: inherits dark text color
// Dark theme: inherits light text color
<Icon name="Settings" />

// Custom color (overrides theme)
<Icon name="Heart" color="#EF4444" />

Component Props

Icon Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | name | keyof typeof icons | - | Icon name from Lucide (required) | | size | number \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Icon size | | color | string | 'currentColor' | Icon color | | strokeWidth | number | 2 | Stroke width | | className | string | '' | Additional CSS classes | | onClick | (e: MouseEvent) => void | - | Click handler | | ariaLabel | string | - | Accessible label |

Examples

Theme Toggle Button

import { IconButton } from '@bttr/icons';

function ThemeToggle({ theme, onToggle }) {
  return (
    <IconButton
      icon={theme === 'light' ? 'Sun' : 'Moon'}
      onClick={onToggle}
      ariaLabel={`Switch to ${theme === 'light' ? 'dark' : 'light'} mode`}
      tooltip="Toggle theme"
    />
  );
}

Action Toolbar

import { IconButton } from '@bttr/icons';

function Toolbar() {
  return (
    <div className="flex gap-2">
      <IconButton icon="Plus" colorScheme="accent" ariaLabel="Add new" />
      <IconButton icon="Pencil" ariaLabel="Edit" />
      <IconButton icon="Copy" ariaLabel="Copy" />
      <IconButton icon="Trash2" colorScheme="danger" ariaLabel="Delete" />
    </div>
  );
}

Interactive Icons

import { Icon } from '@bttrlabs/icons';

function LikeButton() {
  const [liked, setLiked] = useState(false);

  return (
    <button onClick={() => setLiked(!liked)}>
      <Icon
        name="Heart"
        size="lg"
        color={liked ? '#EF4444' : 'currentColor'}
        className={liked ? 'fill-current' : ''}
        ariaLabel={liked ? 'Unlike' : 'Like'}
      />
    </button>
  );
}

Storybook

View all available icons and interactive examples in Storybook:

pnpm run dev

Navigate to:

• Icons/Icon - Browse all 1450+ icons with search
• Icons/IconButton - Interactive button examples and variants

Icon Guidelines

• Default size: 24px (md) for most use cases
• Stroke width: 2 (default) for consistency
• Accessibility: Always provide ariaLabel for standalone icons
• Color: Use currentColor for theme adaptation, custom colors for emphasis
• Spacing: Icons should have adequate padding when clickable

Common Icon Name Reference

Lucide React v0.368 uses different names for some common icons. Here's a quick reference:

| Common Name | Lucide Name | Usage | |-------------|-------------|-------| | Edit | Pencil | Basic edit icon | | Edit (line style) | PencilLine | Edit with line variant | | Edit (with ruler) | PencilRuler | Edit with ruler | | More Horizontal | Ellipsis | Three horizontal dots | | More Vertical | EllipsisVertical | Three vertical dots | | Check Circle | CircleCheck | Success/completed state | | Alert Circle | CircleAlert | Alert/warning state | | Alert Triangle | TriangleAlert | Warning triangle | | Help Circle | CircleHelp | Help/info icon | | X Circle | CircleX | Error/close state | | Unlock | LockOpen | Unlocked state |

Tip: Use the Storybook Icon Gallery to search and discover all available icons with their correct names.

License

MIT