✨ Features

• 🎨 21+ Beautiful Icons - Growing collection of carefully crafted icons
• 🤖 AI-Powered - Generate custom icons with AI or get smart search suggestions
• ⚡ Tree Shakeable - Only bundle the icons you use
• 🎯 Fully Customizable - Size, color, and stroke width props on every icon
• 📦 TypeScript Support - Full type definitions included
• 🎭 Accessible - Built with accessibility in mind
• 🚀 Zero Dependencies - Lightweight and fast
• 💻 Developer First - Simple API, great DX

📦 Installation

Install UltraIcons using your preferred package manager:

# npm
npm install ultraicons

# yarn
yarn add ultraicons

# pnpm
pnpm add ultraicons

🚀 Quick Start

For React/Next.js Projects

npm install ultraicons

// Import individual icons (tree-shakeable)
import { SearchIcon, HeartIcon, StarIcon } from 'ultraicons'

function App() {
  return (
    <div>
      <SearchIcon size={24} color="#000" />
      <HeartIcon size={32} color="red" />
      <StarIcon size={24} strokeWidth={2} />
    </div>
  )
}

For Non-React Projects

npm install ultraicons

// Copy SVG files from node_modules to your assets
// Then use them as regular images or inline SVG

<img src="node_modules/ultraicons/public/icons/search.svg" alt="Search" />

<!-- Or inline SVG for styling -->
<svg><!-- Copy contents from .svg file --></svg>

What you get:

• ✅ React Components - All 117+ icons as tree-shakeable React components
• ✅ TypeScript Support - Full type definitions included
• ✅ SVG Files - Raw SVG files in public/icons/ for non-React use
• ✅ Zero Runtime Dependencies - Pure React, no external dependencies

📖 Usage

React Components (Primary Method)

All icons are exported as React components - this is how most users will consume the package:

import { HomeIcon, UserIcon, SettingsIcon } from 'ultraicons'

function Navigation() {
  return (
    <nav>
      <a href="/">
        <HomeIcon size={24} />
        Home
      </a>
      <a href="/profile">
        <UserIcon size={24} />
        Profile
      </a>
      <a href="/settings">
        <SettingsIcon size={24} />
        Settings
      </a>
    </nav>
  )
}

Benefits:

• 🌲 Tree-shakeable - Only bundle icons you actually use
• 🎨 Dynamic props - Change size, color, stroke width at runtime
• ⚛️ React-native - Works with React and React Native
• 📦 TypeScript - Full type safety and autocomplete

Props

All icons accept the following props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | size | number | 24 | Icon size in pixels | | color | string | "currentColor" | Icon color (any valid CSS color) | | strokeWidth | number | 2 | Stroke width of icon paths | | className | string | "" | Additional CSS classes |

Customization Examples

Size:

<SearchIcon size={16} />  // Small
<SearchIcon size={24} />  // Medium (default)
<SearchIcon size={32} />  // Large
<SearchIcon size={48} />  // Extra large

Color:

<HeartIcon color="#ff0000" />              // Hex
<HeartIcon color="rgb(255, 0, 0)" />       // RGB
<HeartIcon color="red" />                   // Named color
<HeartIcon color="currentColor" />          // Inherit (default)

Stroke Width:

<SearchIcon strokeWidth={1} />   // Thin
<SearchIcon strokeWidth={2} />   // Normal (default)
<SearchIcon strokeWidth={3} />   // Bold

With CSS Classes:

<SearchIcon className="hover:text-blue-500 transition-colors" />

// Tailwind CSS
<SearchIcon className="text-gray-600 dark:text-gray-300" />

Dynamic Styling

import { HeartIcon } from 'ultraicons'
import { useState } from 'react'

function LikeButton() {
  const [liked, setLiked] = useState(false)
  
  return (
    <button onClick={() => setLiked(!liked)}>
      <HeartIcon 
        size={24} 
        color={liked ? 'red' : 'gray'}
        strokeWidth={liked ? 3 : 2}
      />
    </button>
  )
}

🎨 Available Icons

Browse all 117+ icons at ultraicons.com

📥 Using SVG Files Directly

Option 1: From npm package After installing, SVG files are available in node_modules/ultraicons/public/icons/:

# Copy SVG files to your project
cp -r node_modules/ultraicons/public/icons ./src/assets/icons

<!-- Use in HTML -->
<img src="/icons/search.svg" alt="Search" />

Option 2: Download from website Visit ultraicons.com to:

• ⬇️ Download individual SVG files
• 📋 Copy SVG code to clipboard
• 🔍 Search and filter by category
• 🎨 Preview in different themes

🆕 Contributing New Icons

Help grow the library by contributing new icons:

Method 1: Via Website (Recommended)

1. Visit ultraicons.com/create
2. Create your icon manually or use AI generation
3. Preview in different themes and sizes
4. Submit for review - creates a PR automatically

Method 2: Direct PR to Repository

1. Fork the repository
2. Add your SVG to public/icons/ (kebab-case naming)
3. Run npm run extract-icons to update registry
4. Create React component in lib/icons/icons-extended.tsx
5. Export from lib/icons/index.ts
6. Submit pull request

See CONTRIBUTING.md for detailed guidelines.

SVG Format Requirements

<svg xmlns="http://www.w3.org/2000/svg" 
     width="24" height="24" 
     viewBox="0 0 24 24" 
     fill="none" 
     stroke="currentColor" 
     stroke-width="2" 
     stroke-linecap="round" 
     stroke-linejoin="round">
  <!-- Your icon paths here -->
</svg>

Icon Categories

Current collection includes:

• Core (5): Search, Home, User, Settings, Bell
• Social (6): Heart, Star, Thumbs Up/Down, Eye
• Navigation (8): Arrows, Chevrons
• Communication (5): Mail, Phone, Message, Chat
• Files (3): File, Folder, Folder Open
• Media (5): Image, Video, Music, Camera, Microphone
• Actions (5): Edit, Delete, Save, Share, Link
• Status (7): Alert, Info, Check, Error icons
• Devices (3): Monitor, Smartphone, Laptop
• Weather (5): Cloud, Rain, Snow, Sun, Moon
• Development (4): Database, Server, Terminal, Package
• And many more!

🤖 AI Features

AI Icon Generation

Visit ultraicons.com to use our AI-powered icon generator. Describe the icon you need, and our AI will generate it for you.

Smart Search

Our intelligent search provides suggestions and helps you find the right icon even if you don't know its exact name.

Icon Contributions

Submit your own icons through our website. All contributions are AI-reviewed for quality and consistency.

📚 Documentation

For comprehensive documentation, examples, and guides, visit:

• Full Documentation: ultraicons.com/docs
• API Reference: ultraicons.com/docs#api-reference
• Examples: ultraicons.com/docs#examples

🛠️ TypeScript

UltraIcons is built with TypeScript and includes full type definitions:

import { SearchIcon, type IconProps } from 'ultraicons'

// All icons accept IconProps
interface IconProps {
  size?: number
  color?: string
  strokeWidth?: number
  className?: string
}

// Use with your own components
const MyIcon: React.FC<IconProps> = (props) => {
  return <SearchIcon {...props} />
}

🌳 Tree Shaking

UltraIcons supports tree shaking out of the box. Only the icons you import will be included in your bundle:

// ✅ Good - Only SearchIcon is bundled
import { SearchIcon } from 'ultraicons'

// ❌ Avoid - Imports entire library
import * as Icons from 'ultraicons'

🎯 Bundle Size

Each icon is approximately 200-500 bytes when minified and gzipped. The package is designed to be lightweight and efficient.

♿ Accessibility

All icons include proper ARIA attributes and are designed to be accessible. Decorative icons automatically include aria-hidden="true".

🤝 Contributing

We welcome contributions! Here's how you can help:

Adding New Icons

UltraIcons makes it easy to contribute new icons to the library. Follow these steps:

1. Login to the Platform

• Visit ultraicons.com/login
• Sign in with your GitHub account (or use demo mode for testing)
• Authentication is required to submit icons

2. Navigate to Icon Creator

• After logging in, go to ultraicons.com/create
• You'll see two options: Manual SVG creation or AI generation

3. Create Your Icon

Option A: Manual SVG

• Write or paste your SVG code directly
• Ensure your SVG follows these guidelines:
  • Use 24x24 viewBox for consistency
  • Use stroke="currentColor" for theme support
  • Keep stroke-width at 2 for uniformity
  • Use stroke-based designs (not filled)
  • Keep paths clean and simple

Option B: AI Generation

• Describe your icon in natural language
• Example: "A simple house with a chimney and door"
• Click "Generate Icon with AI"
• Review and edit the generated SVG if needed

4. Fill Icon Details

• Icon Name: Use lowercase kebab-case (e.g., home, arrow-right, user-settings)
• Category: Choose appropriate category (e.g., navigation, ui, social, media)
• Tags: Add comma-separated keywords for searchability

5. Preview & Submit

• Review your icon in different:
  • Themes (light/dark/colored)
  • Sizes (16px, 24px, 32px, 48px)
• Check the generated usage code
• Click "Submit Icon for Review"

6. PR Creation

Your icon submission will:

• Be saved to svgIcons/default/ directory
• Automatically create a Pull Request to the repository
• Include all metadata (name, category, tags)
• Be reviewed by maintainers

7. Review Process

• Maintainers will review your PR
• Icons may receive feedback for improvements
• Once approved, your icon will be:
  • Merged into the main branch
  • Published in the next package version
  • Available to all UltraIcons users!

Icon Design Guidelines

✅ Do:

• Use 24x24 viewBox
• Keep designs simple and recognizable
• Use currentColor for theme adaptability
• Follow stroke-based style (2px stroke-width)
• Make icons work at small sizes
• Test in both light and dark themes

❌ Don't:

• Include scripts or event handlers
• Use fixed colors (except for brand icons)
• Make overly complex paths
• Use raster images or external resources
• Include unnecessary metadata

Other Ways to Contribute

• Report Issues: Open an issue on GitHub
• Improve Documentation: Submit PRs to improve our docs
• Spread the Word: Star the repo and share with others

See CONTRIBUTING.md for detailed guidelines.

📄 License

UltraIcons is released under the MIT License.

🔗 Links

• Website: ultraicons.com
• Documentation: ultraicons.com/docs
• GitHub: github.com/logan-exe/ultraicons
• npm: npmjs.com/package/ultraicons
• Issues: github.com/logan-exe/ultraicons/issues

💖 Support

If you find UltraIcons useful, please consider:

• ⭐ Starring the repo on GitHub
• 🐦 Sharing it on social media
• 🤝 Contributing new icons or improvements