dioxus-iconify 0.4.2

# dioxus-iconify

> CLI tool for importing/vendoring icons from [Iconify](https://icon-sets.iconify.design/) (material, lucid, heroicons,....) or from local SVG files in Dioxus projects.

[![Crates.io](https://img.shields.io/crates/v/dioxus-iconify.svg)](https://crates.io/crates/dioxus-iconify)
[![License](https://img.shields.io/crates/l/dioxus-iconify)
](LICENSE)
![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/davidB/dioxus-iconify/total)

Use any of the **275,000+ icons** from [Iconify](https://iconify.design) in your Dioxus applications with a simple CLI tool. Icons are generated at build time as Rust source code, eliminating runtime dependencies.

## ✨ Features

- 🎨 **275k+ Icons**: Access icons from Material Design, Heroicons, FontAwesome, Lucide, and [200+ other icon sets](https://icon-sets.iconify.design/)
- 📁 **Local SVG Support**: Import your own SVG files or entire directories
- 🦀 **Type-Safe**: Generated as Rust const values, checked at compile time
- 📦 **Zero Runtime Dependencies**: No need to depend on this crate at compile time and runtime - only Dioxus
- 🗂️ **Well Organized**: Icons grouped by collection in separate files
- 🎯 **Fully Customizable**: Override any SVG attribute (size, color, stroke, etc.)
- 💾 **Git-Friendly**: Generated code is committed to your repository
- ⚡ **CLI-Based**: Simple `add` command inspired by shadcn-ui and dioxus components

## 🚀 Quick Start

### Installation

```bash
cargo install dioxus-iconify

# via cargo-binstall
cargo binstall dioxus-iconify

# brew (mac & linux)
brew install davidB/tap/dioxus-iconify

# via mise (cli or configuration file)
mise install "ubi:davidB/dioxus-iconify"

# curl + bash script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/davidB/dioxus-iconify/releases/download/latest/dioxus-iconify-installer.sh | sh
```

### Usage

0. **Choose your icons** on [Iconify - home of open source icons](https://icon-sets.iconify.design/)

1. **Add icons to your project**:

```bash
# Add icons from Iconify
dioxus-iconify add mdi:home

# Add multiple icons
dioxus-iconify add mdi:home mdi:account heroicons:arrow-left

# Add local SVG file
dioxus-iconify add ./assets/logo.svg

# Add all SVGs from a directory (recursively)
dioxus-iconify add ./assets/icons/

# Mix Iconify and local icons
dioxus-iconify add mdi:home ./custom/logo.svg heroicons:star

# Skip icons that already exist (don't overwrite)
dioxus-iconify add --skip-existing ./assets/icons/

# Specify custom output directory
dioxus-iconify --output src/components/icons add lucide:settings
```

2. **Use in your Dioxus Element**:

```rust
mod icons;
use crate::icons::{Icon, mdi};

use dioxus::prelude::*;

fn App() -> Element {
    rsx! {
        div {
            // Basic usage
            Icon { data: mdi::Home }

            // Custom size
            Icon {
                data: mdi::Home,
                size: "1.2em", // for same width & height
            }

            Icon {
                data: mdi::Home,
                width: 42,
                height: "24",
            }

            // Custom color and style
            Icon {
                data: mdi::Home,
                fill: "blue",
                class: "icon-class",
            }
        }
    }
}
```

<details>
<summary>(Optional) **Create your application iconset with aliases**</summary>
Advantages: Hide the name of external iconset / collection, ease maintainance, ease switching and mixing of collections.

Create a module to alias other `icons/app.rs`

```rust
// My application iconset
// - aliasing icon from other iconset to not expose other iconset outside
pub use super::heroicons::ArrowLeft;
pub use super::mdi::Home as House;
```

Only pub this module in `icons/mod.rs` (to redo after each `dioxus-iconify update`)

```rust
// ...
pub mod app;
mod heroicons;
mod mdi;
```

Use icons data from `icons::app::*`;

```rust
mod icons;
use crate::icons::{Icon, app};

use dioxus::prelude::*;

fn App() -> Element {
    rsx! {
        div {
            Icon { data: app::House }
            Icon { data: app::ArrowLeft }
        }
    }
}
```

</details>

## 📚 How It Works

### The Problem

Existing Dioxus icon libraries typically bundle all icons in the crate, leading to:

- Large dependency sizes
- Slower compile times
- Including icons you don't use

### The Solution

`dioxus-iconify` takes inspiration from [shadcn-ui](https://ui.shadcn.com/): instead of shipping icons as a dependency, it **generates the icon code directly in your project**.

### What Gets Generated

When you run `dioxus-iconify add mdi:home heroicons:arrow-left`, it creates:

```
src/icons/
├── mod.rs         # Icon component + IconData struct + module declarations
├── mdi.rs         # Material Design Icons: Home, ...
└── heroicons.rs   # Heroicons: ArrowLeft, ...
```

**src/icons/mod.rs**:

```rust
// Auto-generated by dioxus-iconify - DO NOT EDIT
use dioxus::prelude::*;

#[derive(Clone, Copy, PartialEq)]
pub struct IconData {
    pub name: &'static str,
    pub body: &'static str,
    pub view_box: &'static str,
    pub width: &'static str,
    pub height: &'static str,
}

#[component]
pub fn Icon(
    data: IconData,
    /// Optional size to set both width and height
    #[props(default, into)]
    size: String,
    /// Additional attributes to extend the svg element
    #[props(extends = SvgAttributes)]
    attributes: Vec<Attribute>,
) -> Element {
    let (width, height) = if size.is_empty() {
        (data.width, data.height)
    } else {
        (size.as_str(), size.as_str())
    };

    rsx! {
        svg {
            view_box: "{data.view_box}",
            width: "{width}",
            height: "{height}",
            dangerous_inner_html: "{data.body}",
            ..attributes,
        }
    }
}

pub mod heroicons;
pub mod mdi;
```

**src/icons/mdi.rs**:

```rust
// Auto-generated by dioxus-iconify - DO NOT EDIT
// Collection: mdi

use super::IconData;

pub const Home: IconData = IconData {
    name: "mdi:home",
    body: r#"<path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>"#,
    view_box: "0 0 24 24",
    width: "24",
    height: "24",
};
```

## 🎨 Icon Customization

The `Icon` component uses Dioxus 0.7's `extends = SvgAttributes` pattern, allowing you to override any SVG attribute:

```rust
Icon {
    data: mdi::Home,
    // Size
    width: "48",
    height: "48",

    // Color
    fill: "currentColor",
    stroke: "#000000",
    stroke_width: "2",

    // CSS
    class: "my-icon hover:text-blue-500",
    style: "margin: 1rem;",

    // Accessibility
    aria_label: "Home icon",
    role: "img",

    // Any other SVG attribute...
}
```

## 🔍 Finding Icons

Browse available icons at:

- [Iconify Icon Sets](https://icon-sets.iconify.design/)
- [Icônes](https://icones.js.org/)

Icon names follow the format `collection:icon-name`:

- `mdi:home` - Material Design Icons
- `heroicons:arrow-left` - Heroicons
- `lucide:settings` - Lucide
- `fa:github` - Font Awesome
- `simple-icons:rust` - Simple Icons

## 📖 CLI Commands

### `add`

Add icons to your project from Iconify API or local SVG files:

```bash
dioxus-iconify add [OPTIONS] <ICONS>...

Options:
  --skip-existing    Skip icons that already exist (don't overwrite)

# Iconify API icons
dioxus-iconify add mdi:home
dioxus-iconify add mdi:home mdi:account heroicons:arrow-left

# Local SVG files
dioxus-iconify add ./logo.svg
dioxus-iconify add ./assets/icon1.svg ./assets/icon2.svg

# Local directories (scans recursively)
dioxus-iconify add ./assets/icons/
dioxus-iconify add ./icons/social/ ./icons/ui/

# Mix both sources
dioxus-iconify add mdi:home ./custom/logo.svg

# Don't overwrite existing icons
dioxus-iconify add --skip-existing ./assets/icons/

# Custom output directory
dioxus-iconify --output src/components/icons add lucide:settings
```

#### Local SVG Files

When adding local SVG files:

- **Single files**: Collection name is taken from the parent directory name
  - `./assets/logo.svg` → collection: `assets`, icon: `logo`
- **Directories**: Collection name is the directory name, icons are scanned recursively
  - `./my-icons/home.svg` → `my-icons:home`
  - `./my-icons/arrows/left.svg` → `my-icons:arrows-left`
- **SVG processing**: Automatically extracts dimensions from `width`, `height`, and `viewBox` attributes
- **Missing dimensions**: Defaults to 24x24 if not specified in the SVG

### `init`

Initialize the icons directory (creates `mod.rs`):

```bash
dioxus-iconify init
```

### `list`

List all generated icons:

```bash
dioxus-iconify list
```

### `update`

Re-fetch and update all icons from Iconify API:

```bash
dioxus-iconify update
```

### Coming Soon

- `remove` - Remove icons from your project

## 🆚 Comparison with Other Solutions

| Feature          | dioxus-iconify | Embedded Libraries | SVG Files |
| ---------------- | -------------- | ------------------ | --------- |
| Icon Count       | 275,000+       | Limited            | Manual    |
| Uptodate Icons   | ✅             | Depends            | Manual    |
| Dependency Size  | 0 (CLI only)   | Large              | 0         |
| Type Safety      | Mixed          | ✅                 | ❌        |
| Customization    | Full           | Limited            | Full      |
| Fixes/workaround | Full           | Take time          | Full      |
| Offline Support  | ✅ (committed) | ✅                 | ✅        |
| Updates          | CLI command    | Crate update       | Manual    |

Some Embedded libraries of icons for dioxus:
[dioxus-free-icons](https://crates.io/crates/dioxus-free-icons),
[dioxus-material-icons](https://crates.io/crates/dioxus-material-icons),
[dioxus-heroicons](https://crates.io/crates/dioxus-heroicons),
...

[Search Results for 'dioxus icons' - crates.io: Rust Package Registry](https://crates.io/search?q=dioxus%20icons)

## 💡 Tips

1. **Commit generated code**: The `src/icons/` directory should be committed to version control
2. **Customize the Icon component**: It's generated in your project, so modify it if needed
3. **Use with Tailwind**: Icon colors work with Tailwind's `text-*` classes via `currentColor`
4. **Organization**: Icons are automatically grouped by collection in separate files
5. **Local SVGs**: Use the `--skip-existing` flag when adding directories to avoid overwriting customized icons
6. **Nested directories**: Icons in subdirectories are automatically named with hyphens (e.g., `arrows/left.svg` becomes `arrows-left`)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 🙏 Acknowledgments

- [Dioxus](https://dioxuslabs.com/) - The amazing Rust UI framework
- [Iconify](https://iconify.design/) - For providing the amazing icon API and collections

### For inspiration

- [shadcn-ui](https://ui.shadcn.com/) - For inspiration on the CLI-based generation approach
- [Dioxus Components](https://dioxuslabs.com/components) - Like shadcn but for dioxus
- [iconmate](https://github.com/Blankeos/iconmate) - For similar ideas in the TypeScript ecosystem

## 📚 Resources

- [Iconify Documentation](https://iconify.design/docs/)
- [Dioxus Documentation](https://dioxuslabs.com/learn/)
- [Browse Icons](https://icon-sets.iconify.design/)