TypedIcons 0.5.0

TypedIcons

TypedIcons is a tool for using Iconify icons in Blazor with full type safety and IntelliSense support.

Instead of relying on string-based icon names, TypedIcons uses a .NET CLI and source generator to generate strongly-typed access to icons from Iconify icon sets. This means you get compile-time validation, auto-completion, and a much better developer experience when working with icons.

Icons are added through the CLI and resolved at build time, so there are no runtime dependencies, no dynamic loading, and no unnecessary overhead. Everything is known at compile time, making icon usage predictable and safe.

The goal of TypedIcons is simple: make working with icons in Blazor feel like working with any other strongly-typed part of your codebase.

Table of Contents

• Installation
  • CLI Tool
  • Source Generator
• Usage
  • Initializing a Project
  • Adding Icons
  • Removing Icons
  • Listing Icons
  • Managing Aliases
  • Standalone Components
  • Using Icons in Components
  • Restoring Icons
  • Cleaning the Cache
  • CLI Reference
• Manual Setup
• How It Works
• Support the Project
• Contributing
• License
• Acknowledgment

Installation

TypedIcons consists of two components: the CLI tool and the source generator. The CLI is installed once globally (or locally), and the source generator is added to your Blazor project automatically by the CLI.

CLI Tool

Install the TypedIcons CLI as a global .NET tool:

dotnet tool install --global TypedIcons

Or install it locally from a directory:

dotnet tool install --global --add-source <user_directory> TypedIcons

To update the tool to the latest version:

dotnet tool update --global TypedIcons

Source Generator

The source generator (TypedIcons.Generator) is installed automatically into your Blazor project when you run typedicons init and confirm the prompt. If you prefer to add it manually, see the Manual Setup section below.

Usage

Initializing a Project

Run the following command from your Blazor project directory (where your .csproj file is located):

typedicons init

The CLI will:

1. Detect your .csproj file
2. Create a typedicons.json configuration file
3. Create a local icon cache in the obj folder
4. Offer to install the TypedIcons.Generator source generator into your project
5. Offer to automatically add @using TypedIcons to Components/_Imports.razor

Example output:

Found project: MyBlazorApp.csproj
Created typedicons.json
Created cache file
Do you want to install the TypedIcons source generator? [y/n] (y): y
Installing package...
Source generator package installed successfully
Do you want to automatically add @using TypedIcons to Components/_Imports.razor? [y/n] (y): y
Added @using TypedIcons to Components/_Imports.razor
TypedIcons initialized successfully

To skip all confirmation prompts and accept defaults, use the -y flag:

typedicons init -y

Adding Icons

Add any icon from Iconify using the <set>:<icon> format:

typedicons add boxicons:air-conditioner
typedicons add lucide:home
typedicons add mdi:account-circle

After adding an icon, the source generator will regenerate the strongly-typed classes. This is usually automatic and near-instant, but if the changes don't appear in your IDE immediately, try rebuilding the project or restarting your IDE.

Removing Icons

Remove an icon from your project using the same <set>:<icon> format:

typedicons remove lucide:home
typedicons remove mdi:account-circle

Listing Icons

List all icons currently in your project:

typedicons list

Filter by icon set:

typedicons list --set lucide

Search by name:

typedicons list house

Combine both:

typedicons list --set lucide house

Managing Aliases

Aliases let you access icons via a shorthand name directly on the Icons class, without specifying the set:

<Icon Source="Icons.House" />        @* alias *@
<Icon Source="Icons.Lucide.House" /> @* full path *@

Add an alias to an existing icon:

typedicons alias add lucide:house House

Remove an alias from an icon by icon name:

typedicons alias remove lucide:house

Or by alias name directly:

typedicons alias remove House

List all icons that have aliases:

typedicons alias list

Or assign an alias when first adding an icon:

typedicons add lucide:house --alias House

Standalone Components

Standalone components let you use icons directly as named Blazor components, without the <Icon> wrapper:

<MdiHome Size="5em" />       @* by set + name *@
<House Size="5em" />         @* via alias *@

⚠️ Required setup: Due to Blazor's source generator pipeline, standalone components require the following property in your .csproj:

<PropertyGroup>
    <UseRazorSourceGenerator>false</UseRazorSourceGenerator>
</PropertyGroup>

Without this, standalone components will not be rendered at runtime.

Add a standalone component to an existing icon:

typedicons standalone add mdi:home

Remove a standalone component from an icon:

typedicons standalone remove mdi:home

List all icons with standalone components:

typedicons standalone list

Or generate a standalone component when first adding an icon:

typedicons add mdi:home --standalone

Combine with an alias for the cleanest usage:

typedicons add mdi:home --alias Home --standalone

This gives you all four ways to use the icon:

<Icon Source="Icons.Mdi.Home" />   @* full path *@
<Icon Source="Icons.Home" />       @* alias *@
<MdiHome />                        @* standalone *@
<Home />                           @* standalone + alias *@

Using Icons in Components

Once icons are added, use them via the <Icon> component anywhere in your Blazor markup:

<Icon Source="Icons.Boxicons.AirConditioner" Size="5em" />
<Icon Source="Icons.Heroicons.Backspace" Size="5em" />

Icons are accessed through the generated Icons.<Set>.<Name> static classes, giving you full IntelliSense and compile-time validation.

Parameters

Parameter	Type	Description
Source	IconDefinition	The icon to render (required)
Size	string?	Sets both width and height (e.g. "24px", "1.5em"). Takes precedence over Width and Height
Width	string?	Overrides the icon's intrinsic width
Height	string?	Overrides the icon's intrinsic height
Class	string?	CSS class(es) applied to the root <svg> element
Style	string?	Inline styles applied to the root <svg> element
Title	string?	Accessible title. When set, icon is meaningful (role="img"). When omitted, icon is decorative (aria-hidden="true")
ChildContent	RenderFragment?	Optional content rendered inside the <svg> after the icon paths
AdditionalAttributes	Dictionary<string, object>?	Additional attributes passed through to the root <svg> element

Restoring Icons

The icon cache lives in the obj folder and is not committed to source control — only typedicons.json is. After cloning a repository or deleting the obj folder, restore the cache by running:

typedicons restore

To force a full re-fetch — clearing the cache and restoring from Iconify in one step:

typedicons restore --force

It's a good practice to add typedicons restore to your project's setup instructions or run it as part of your build process.

Cleaning the Cache

To clear the local icon cache without restoring:

typedicons clean

This removes all cached SVG data from the obj folder. Run typedicons restore afterward to re-fetch.

CLI Reference

USAGE:
    typedicons [OPTIONS] <COMMAND>

OPTIONS:
    -h, --help       Prints help information
    -v, --version    Prints version information

COMMANDS:
    init                           Initialize TypedIcons in the current project
    add <name>                     Add an icon by name (<set>:<icon>)
        --alias <alias>            Assign a shorthand alias to the icon
        --standalone               Generate a standalone component for the icon
    remove <name>                  Remove an icon by name (<set>:<icon>)
    list [search]                  List all icons in the current project
        --set <set>                Filter by icon set
    restore                        Restore icons in the local cache
        --force                    Force re-fetch (clears cache and restores from Iconify)
    clean                          Clean local icon cache
    alias                          Manage icon aliases
        add <name> <alias>         Add an alias for an icon (<set>:<icon>)
        remove <name|alias>        Remove an alias by icon name (<set>:<icon>) or alias name
        list [search]              List all icons with aliases
    standalone                          Manage standalone icon components
        add <name>                      Add a standalone component for an icon (<set>:<icon>)
        remove <name>                   Remove a standalone component from an icon (<set>:<icon>)
        list [search]                   List all standalone icon components

---

Manual Setup

If you prefer not to use typedicons init, you can set up TypedIcons manually.

1. Create typedicons.json in your project root:

{
  "icons": []
}

2. Add the source generator to your .csproj:

<ItemGroup>
    <PackageReference Include="TypedIcons.Generator" Version="X.Y.Z"/>
</ItemGroup>

Replace X.Y.Z with the latest version.

3. Add the using directive to Components/_Imports.razor:

@using TypedIcons

You can then use typedicons add as normal to add icons to your project.

---

How It Works

TypedIcons bridges Iconify's vast icon library with .NET's type system:

• typedicons.json is the source of truth — it lists every icon your project uses and is committed to source control.
• The icon cache (in obj/) holds the downloaded SVG data locally. It is generated from typedicons.json and is excluded from source control.
• The source generator reads typedicons.json and the icon cache at build time and emits strongly-typed C# classes, giving you IntelliSense and compile-time safety in your Blazor components.

Note: The source generator runs automatically in most cases. However, due to Roslyn and IDE quirks, you may occasionally need to rebuild your project or restart your IDE for changes to take effect.

---

Support the Project

If you find this project useful, consider supporting it by buying me a coffee. Your support is greatly appreciated!

Contributing

Contributions are welcome! If you have a feature to propose or a bug to fix, create a new pull request.

License

This project is licensed under the MIT License.

Acknowledgment

This project is built with the help of Iconify icon sets and API.

Project icon designed by ThatSebastjan.