Documentation
Everything you need to know about using UltraIcons in your React projects.
Installation
Install UltraIcons using your preferred package manager:
npm install ultraiconsRequirements
- •React 18.0.0 or higher
- •TypeScript support (optional but recommended)
Usage
Basic Usage
Import and use icons as React components:
import { SearchIcon, HeartIcon } from 'ultraicons'
function MyComponent() {
return (
<div>
<SearchIcon size={24} color="#000" />
<HeartIcon size={24} color="red" />
</div>
)
}Available Props
| Prop | Type | Default | Description |
|---|---|---|---|
| size | number | 24 | Icon size in pixels |
| color | string | "currentColor" | Icon color (CSS color value) |
| strokeWidth | number | 2 | Stroke width of icon paths |
| className | string | "" | Additional CSS classes |
Tree Shaking
UltraIcons supports tree shaking out of the box. Only the icons you import will be included in your bundle, keeping your application size optimized.
Customization
Size Customization
Control icon size using the size prop:
<SearchIcon size={16} /> // Small
<SearchIcon size={24} /> // Medium (default)
<SearchIcon size={32} /> // Large
<SearchIcon size={48} /> // Extra largeColor Customization
Customize icon colors with CSS color values:
// Hex colors
<HeartIcon color="#ff0000" />
// RGB colors
<HeartIcon color="rgb(255, 0, 0)" />
// CSS color names
<HeartIcon color="red" />
// currentColor (inherits from parent)
<HeartIcon color="currentColor" />Stroke Width
Adjust stroke width for different visual weights:
<SearchIcon strokeWidth={1} /> // Thin
<SearchIcon strokeWidth={2} /> // Normal (default)
<SearchIcon strokeWidth={3} /> // BoldCSS Classes
Add custom styling with className:
<SearchIcon
className="hover:text-blue-500 transition-colors"
/>
// With Tailwind CSS
<SearchIcon className="text-gray-600 dark:text-gray-300" />AI Features
AI Icon Generation
UltraIcons includes AI-powered icon generation. Visit the homepage and use the AI Generator to create custom icons based on text descriptions.
Pro Tip: The more specific your description, the better the AI can generate an icon that matches your needs.
Smart Suggestions
When searching for icons, AI provides intelligent suggestions to help you find the perfect icon, even if you don't know the exact name.
Icon Contributions
Submit your own icons to the library. All contributions are reviewed by AI to ensure quality and consistency before being added to the package.
Start ContributingAdding New Icons
Simple File-Based System
UltraIcons uses a simple file-based system. To add a new icon, just drop an SVG file in the public/icons/ directory.
Step 1: Create your SVG file
<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 -->
<circle cx="12" cy="12" r="10" />
<path d="M12 8v8m-4-4h8" />
</svg>Step 2: Save to public/icons/
Name your file using kebab-case: my-icon.svg
public/icons/
├── search.svg
├── home.svg
├── my-icon.svg ← Your new icon
└── ...Step 3: Update the registry
Run the extraction script to update the icon registry:
npm run extract-iconsThis will automatically add your icon to registry.json and make it available in the browser.
Downloading SVG Files
All icons can be downloaded or copied as SVG files directly from the Browse page. Each icon card has download and copy buttons that appear on hover.
- Download: Click the download button to save the SVG file to your computer
- Copy: Click the copy button to copy the SVG code to your clipboard
- Use anywhere: SVG files work in any project, not just React
TypeScript Support
UltraIcons is built with TypeScript and includes full type definitions. All icon components are properly typed:
import { SearchIcon, type IconProps } from 'ultraicons'
// IconProps interface
interface IconProps {
size?: number
color?: string
strokeWidth?: number
className?: string
}API Reference
IconProps Interface
size?: number
The width and height of the icon in pixels. Default: 24
color?: string
The color of the icon. Accepts any valid CSS color value. Default: "currentColor"
strokeWidth?: number
The stroke width of the icon paths. Default: 2
className?: string
Additional CSS classes to apply to the icon SVG element.
Available Icons
View the complete list of available icons by visiting the Browse Icons section on the homepage.
Examples
Button with Icon
import { SearchIcon } from 'ultraicons'
function SearchButton() {
return (
<button className="flex items-center gap-2">
<SearchIcon size={20} />
<span>Search</span>
</button>
)
}Navigation Menu
import { HomeIcon, SettingsIcon, UserIcon } 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>
)
}Dynamic Icon Color
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"}
/>
</button>
)
}FAQ
Can I use UltraIcons in commercial projects?
Yes! UltraIcons is released under the MIT License, which allows use in both personal and commercial projects.
How do I request a new icon?
You can use the AI Generator on the homepage to create new icons, or open an issue on our GitHub repository to request specific icons.
Are the icons accessible?
Yes, all icons include proper ARIA attributes and are designed to be accessible. For decorative icons, they automatically include aria-hidden="true".
What's the bundle size impact?
UltraIcons supports tree shaking, so only the icons you import are included in your bundle. Each icon is approximately 200-500 bytes when minified and gzipped.
Support
Need Help?
If you encounter any issues or have questions, we're here to help: