@hydrogen-ui/icons

A comprehensive icon library for Hydrogen UI with 200+ optimized SVG icons. Features two variants (outlined and filled), TypeScript support, tree-shaking, and an icon provider for consistent styling.

Installation

npm install @hydrogen-ui/icons
# or
yarn add @hydrogen-ui/icons
# or
pnpm add @hydrogen-ui/icons

Features

• 🎨 200+ Icons - Commerce, navigation, actions, and more
• 🎭 Two Variants - Outlined and filled styles
• ⚡ Optimized - SVGO-optimized for minimal file size
• 🌲 Tree-shakeable - Import only what you need
• 🔒 TypeScript - Full type safety and autocompletion
• ♿ Accessible - ARIA labels and proper semantics
• 🎯 Icon Provider - Global configuration support
• 📦 Small Bundle - Minimal impact on your app size

Quick Start

import { CartFilledIcon, HeartOutlinedIcon } from '@hydrogen-ui/icons';

function MyComponent() {
  return (
    <div>
      <CartFilledIcon size={24} color="#000" />
      <HeartOutlinedIcon size={20} color="red" />
    </div>
  );
}

Icon Variants

Each icon comes in two variants:

• Outlined - Stroke-based design, lighter visual weight
• Filled - Solid fill design, heavier visual weight

// Outlined variant
import { HomeOutlinedIcon } from '@hydrogen-ui/icons';

// Filled variant
import { HomeFilledIcon } from '@hydrogen-ui/icons';

// Some icons only have one variant
import { ChevronDownOutlinedIcon } from '@hydrogen-ui/icons';

Icon Categories

Commerce Icons

Shopping, payment, and e-commerce related icons:

• Cart, bag, credit card, shopping tag
• Barcode, receipt, label
• Delivery truck, package

Navigation Icons

Directional and menu icons:

• Arrows, chevrons
• Menu burger, dots
• Home, search

Action Icons

Interactive action icons:

• Plus, minus, close
• Copy, paste, link
• Upload, download, export
• Lock, unlock

Status Icons

Information and state indicators:

• Info, question, warning circles
• Check, cross marks

Object Icons

Files, folders, and media:

• File, folder, image
• Code, terminal
• Database, cloud

Device Icons

Hardware and technology:

• Microchip, CPU, plug
• Microphone, camera
• Printer, scanner

Usage

Basic Usage

All icons accept standard SVG props plus some additional options:

import { SearchAlt1FilledIcon } from '@hydrogen-ui/icons';

<SearchAlt1FilledIcon 
  size={24}               // or width/height
  color="currentColor"    // or fill for filled, stroke for outlined
  className="search-icon"
  onClick={handleClick}
  title="Search"          // Adds accessible title
/>

Icon Provider

Use the IconProvider to set default props for all child icons:

import { IconProvider, CartFilledIcon, HeartFilledIcon } from '@hydrogen-ui/icons';

function App() {
  return (
    <IconProvider size={20} color="#333" className="app-icon">
      <CartFilledIcon />      {/* Inherits size=20, color=#333 */}
      <HeartFilledIcon />     {/* Inherits size=20, color=#333 */}
      <SearchIcon size={24} /> {/* Overrides size to 24 */}
    </IconProvider>
  );
}

Dynamic Icon Selection

Load icons dynamically based on a string:

import * as icons from '@hydrogen-ui/icons';

function DynamicIcon({ name, ...props }) {
  const Icon = icons[name as keyof typeof icons];
  
  if (!Icon) {
    console.warn(`Icon ${name} not found`);
    return null;
  }
  
  return <Icon {...props} />;
}

// Usage
<DynamicIcon name="CartFilledIcon" size={24} />

Icon Catalog

Access icon metadata programmatically:

import { iconCatalog } from '@hydrogen-ui/icons';

// Get all commerce icons
const commerceIcons = Object.entries(iconCatalog)
  .filter(([name, meta]) => meta.category === 'commerce')
  .map(([name]) => name);

// Search icons by keywords
const searchIcons = Object.entries(iconCatalog)
  .filter(([name, meta]) => 
    meta.keywords.some(keyword => 
      keyword.includes('search')
    )
  );

Props

All icons accept these props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | size | number | 24 | Icon size (sets both width and height) | | width | number | 24 | Icon width | | height | number | 24 | Icon height | | color | string | 'currentColor' | Icon color (fill for filled, stroke for outlined) | | fill | string | - | SVG fill color | | stroke | string | - | SVG stroke color | | strokeWidth | number | 2 (outlined) / 0 (filled) | Stroke width | | className | string | - | CSS class name | | style | CSSProperties | - | Inline styles | | title | string | - | Accessible title | | titleId | string | - | ID for title element | | ...svgProps | SVGAttributes | - | All standard SVG props |

Accessibility

Icons include built-in accessibility features:

// With title - icon is announced to screen readers
<CartFilledIcon title="Shopping cart" />
// Renders: <title id="...">Shopping cart</title>

// Without title - icon is decorative
<CartFilledIcon />
// Renders: aria-hidden="true"

// Custom title ID for ARIA labelling
<button aria-labelledby="cart-icon">
  <CartFilledIcon title="Shopping cart" titleId="cart-icon" />
</button>

Available Icons

Commerce (23 icons)

• Bag4FilledIcon, BagFilledIcon
• Cart1FilledIcon, CartLarge2FilledIcon, CartPlusFilledIcon, CartShoppingFilledIcon, CartOutlinedIcon
• CreditCard1FilledIcon, CreditCardFilledIcon, CreditCardPlusFilledIcon, CreditCardScanFilledIcon
• LabelFilledIcon, LabelPriceSaleFilledIcon
• ShoppingTagFilledIcon, TagFilledIcon, TagOutlinedIcon, TagsFilledIcon
• BarcodeFilledIcon, ReceiptAlt1FilledIcon
• DeliveryFilledIcon, DeliveryTruckFilledIcon

Navigation (37 icons)

• Arrow variants: AltArrowDownFilledIcon, AltArrowLeftFilledIcon, AltArrowRightFilledIcon, AltArrowUpFilledIcon
• Chevron variants: All directions with filled and outlined options
• MenuBurgerFilledIcon, MenuOutlinedIcon
• HomeFilledIcon, HomeOutlinedIcon
• SearchAlt1FilledIcon, MagnifyingGlassOutlinedIcon

Actions (45 icons)

• PlusFilledIcon, PlusCircledOutlinedIcon
• CopyFilledIcon, CopyOutlinedIcon, ClipboardCopyOutlinedIcon
• LinkFilledIcon, PaperclipFilledIcon, PaperclipAltFilledIcon
• UploadFilledIcon, UploadMinimalisticFilledIcon, DownloadFilledIcon
• ExportFilledIcon, PrintFilledIcon, PrinterFilledIcon
• RefreshCwAlt1FilledIcon, RefreshCwAltFilledIcon, ReloadOutlinedIcon
• LockFilledIcon, LockAltFilledIcon, UnlockFilledIcon
• TrashOutlinedIcon

Status (9 icons)

• CircleInfoFilledIcon, InfoCircledOutlinedIcon
• CircleQuestionFilledIcon
• CircleXmarkFilledIcon, CrossCircledOutlinedIcon
• CircleMinusFilledIcon, CirclePlusFilledIcon

Objects (48 icons)

• File variants: FileFilledIcon, FilePlusFilledIcon, FileCopyFilledIcon, FileLockFilledIcon
• Folder variants: FolderFilledIcon, FolderPlusFilledIcon, FolderImageFilledIcon
• ImageFilledIcon, ImagePlusFilledIcon, ImageSquareFilledIcon
• CodeFilledIcon, CodeAltFilledIcon, CodeBranchFilledIcon
• DatabaseFilledIcon, CloudUploadFilledIcon

Device (12 icons)

• MicrochipFilledIcon, CpuFilledIcon, ChipOutlinedIcon
• MicrophoneFilledIcon, MicrophoneAlt1FilledIcon
• CameraFilledIcon
• PrinterFilledIcon, PrinterOutlinedIcon
• ScannerFilledIcon

TypeScript

Full TypeScript support with type exports:

import type { IconProps, IconName } from '@hydrogen-ui/icons';
import { CartFilledIcon } from '@hydrogen-ui/icons';

// Type-safe props
const iconProps: IconProps = {
  size: 24,
  color: 'blue',
  className: 'my-icon'
};

// Type-safe icon names
const iconName: IconName = 'CartFilledIcon';

// Component typing
const MyIcon: React.FC<IconProps> = (props) => {
  return <CartFilledIcon {...props} />;
};

Performance

Tree Shaking

Import only the icons you need:

// ✅ Good - only imports one icon
import { CartFilledIcon } from '@hydrogen-ui/icons';

// ❌ Bad - imports entire library
import * as icons from '@hydrogen-ui/icons';

Bundle Size

Each icon is approximately 1-2KB uncompressed. With tree-shaking, you only pay for what you use:

• Single icon: ~1-2KB
• 10 icons: ~10-20KB
• Provider overhead: ~2KB

Optimization

All icons are pre-optimized with SVGO for minimal file size while maintaining visual quality.

Advanced Usage

Custom Icon Wrapper

Create your own icon wrapper with default styles:

import { CartFilledIcon } from '@hydrogen-ui/icons';

function AppIcon({ name, ...props }) {
  const icons = {
    cart: CartFilledIcon,
    // ... other icons
  };
  
  const Icon = icons[name];
  
  return (
    <Icon
      size={20}
      className="app-icon"
      {...props}
    />
  );
}

Icon Button Component

import { IconProvider } from '@hydrogen-ui/icons';

function IconButton({ icon: Icon, label, onClick, ...props }) {
  return (
    <button
      onClick={onClick}
      className="icon-button"
      aria-label={label}
      {...props}
    >
      <IconProvider size={16} color="currentColor">
        <Icon />
      </IconProvider>
    </button>
  );
}

// Usage
<IconButton 
  icon={CartFilledIcon} 
  label="Add to cart"
  onClick={handleAddToCart}
/>

Animated Icons

Add animations with CSS:

.icon-spin {
  animation: spin 1s linear infinite;
}

@keyframes spin {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}

<RefreshCwAltFilledIcon className="icon-spin" />

Browser Support

• Modern browsers (Chrome, Firefox, Safari, Edge)
• IE11 requires SVG polyfills
• React Native supported via react-native-svg

Contributing

Adding New Icons

1. Add SVG files to raw/archive/filled/ or raw/archive/outlined/
2. Run npm run optimize to optimize SVGs
3. Run npm run generate to create React components
4. Run npm run build to build the package

Icon Guidelines

• Use 24x24 viewBox
• 2px stroke width for outlined icons
• Consistent style with existing icons
• Meaningful, searchable names

License

MIT