Overview

An icon pack is an ordinary .NET class library whose only content is a set of icon files stored as embedded resources. Deploying a single DLL gives your application hundreds, or thousands, of icons. There's no folder of loose image files to copy and keep in sync.

Wisej.NET understands icon packs both at design time and at run time:

• the Visual Studio ImageSource editor finds every icon pack the project references and lists it as a folder, next to the project's own images;
• at run time each icon is served through the resource.wx URL, resource.wx/<AssemblyName>/<file>, so it works in any ImageSource-style property, in HTML and in CSS;
• each pack also has a static Icons class with one constant per icon, so you can use icons in code without typing file names.

Available icon packs

Pack	Icons	Style	NuGet package
BootstrapIcons	1,386	Monochrome outline and fill, 16 px grid	Wisej-4-BootstrapIcons
CssGgIcons	704	Monochrome geometric line icons, 24 px grid	Wisej-4-CssGgIcons
ElegantIcons	294	Monochrome	Wisej-4-ElegantIcons
FeatherIcons	287	Monochrome line icons, 24 px grid	Wisej-4-FeatherIcons
FluentUIFilledIcons	1,060	Monochrome, Fluent Design filled variant, 24 px grid	Wisej-4-FluentUIFilledIcons
FluentUIOutlinedIcons	1,056	Monochrome, Fluent Design outlined variant, 24 px grid	Wisej-4-FluentUIOutlinedIcons
FontAwesome	519	Monochrome, Font Awesome 4	Wisej-4-FontAwesome
IonicIcons	1,332	Monochrome, filled, outline and sharp variants	Wisej-4-IonicIcons
LucideIcons	1,669	Monochrome line icons, 24 px grid	Wisej-4-LucideIcons
MaterialDesign	423	Monochrome, Material style	Wisej-4-MaterialDesign
ModernUI	1,276	Monochrome, Windows "Metro" app bar style	Wisej-4-ModernUI
TablerIcons	1,978	Monochrome line icons, 24 px grid	Wisej-4-TablerIcons
VaadinIcons	636	Monochrome, 16 px grid	Wisej-4-VaadinIcons
VisualStudioIcons	4,668	Multi-colored, Visual Studio image library	Wisej-4-VisualStudioIcons

All packs target .NET Framework 4.8 and .NET 8 or later, and they contain only SVG files. The counts are the icons each assembly embeds. Every pack's page has a searchable browser of its icons, with the constant and the URL of each one ready to copy.

The FluentUI packs and LucideIcons are new in Wisej.NET 4.1 and bring a dependency the others don't have: the Wisej-4-Svg package, a client-side SVG renderer that takes over the rendering of every SVG image in the application once it's referenced. Each of those pages says what that means.

Themes have their own icons

Every Wisej.NET theme already includes a set of icons (icon-print, icon-search, and so on), which you can use by name without any icon pack. See Theme Images. Icon packs are for when you need more icons than the theme provides.

Picking icons in Visual Studio

Once the project references an icon pack, open the ImageSource editor from any image property (ImageSource, Icon, BackgroundImageSource, …). Each referenced pack appears in the folder list on the left, below Project. Select a pack to browse its icons, and use the search box above the list to filter them by name.

The ImageSource editor lists every referenced icon pack as a folder.

By default, monochrome icons are drawn in the icon color of the current theme. To give one icon a specific color, click the palette button on the editor's left toolbar and pick a color.

Choosing a color for the selected icon.

The designer writes the choice into InitializeComponent() as a resource.wx URL. A color becomes a ?color= query parameter:

C#

//
// button1
//
this.button1.ImageSource = "resource.wx/Wisej.Ext.FontAwesome/android.svg?color=Coral";

VB.NET

'
' button1
'
Me.button1.ImageSource = "resource.wx/Wisej.Ext.FontAwesome/android.svg?color=Coral"

The recolored icon on a button, as seen in the designer.

Using icons in code

There are two ways to refer to an icon in code:

• The Icons constants. Every pack has a static class named Icons in the pack's namespace, with one const string per icon. Each constant already holds the full resource.wx URL, so a typo is a compile error instead of a missing image.
• The URL. Use resource.wx/<AssemblyName>/<file-name>.svg directly. This is the form to use when the icon name comes from data, for example a menu stored in a database.

C#

// The constant holds "resource.wx/Wisej.Ext.FontAwesome/print.svg".
this.buttonPrint.ImageSource = Wisej.Ext.FontAwesome.Icons.Print;

// The same icon, by URL.
this.buttonPrint.ImageSource = "resource.wx/Wisej.Ext.FontAwesome/print.svg";

// Recolor it. Named colors, #rrggbb, rgb()/rgba() and theme color names are accepted.
this.buttonPrint.ImageSource = Wisej.Ext.FontAwesome.Icons.Print + "?color=#E53935";

VB.NET

' The constant holds "resource.wx/Wisej.Ext.FontAwesome/print.svg".
Me.buttonPrint.ImageSource = Wisej.Ext.FontAwesome.Icons.Print

' The same icon, by URL.
Me.buttonPrint.ImageSource = "resource.wx/Wisej.Ext.FontAwesome/print.svg"

' Recolor it. Named colors, #rrggbb, rgb()/rgba() and theme color names are accepted.
Me.buttonPrint.ImageSource = Wisej.Ext.FontAwesome.Icons.Print & "?color=#E53935"

The constant names are the file names in PascalCase: house-door.svg becomes HouseDoor, and ModernUI's appbar.home.empty.svg becomes AppbarHomeEmpty. A name that would start with a digit is adjusted, for example 1x.svg becomes _1x in VisualStudioIcons, while TablerIcons spells the digit out (2fa.svg becomes TwoFa). Each pack's page lists its conventions.

Coloring SVG icons

The ?color= parameter and the theme's automatic icon color only change monochrome SVGs. If a custom SVG keeps its color, it probably has hard-coded fill or stroke values. See SVG Colors in the user guide.

Deployment and caching

An icon pack is deployed like any other referenced assembly: the DLL goes into the application's bin folder with the rest. There's nothing to register.

Each icon is a separate resource.wx request, and the browser caches it after the first download. Theme icons work differently: they're embedded in the theme and all reach the client at once when the theme loads. That makes icon packs better suited to a large catalog of icons of which each page uses a few.

Replacing a single icon

A file deployed in the application folder takes precedence over an embedded resource with the same path. To replace one icon of a pack without rebuilding it, deploy your own file as /Wisej.Ext.FontAwesome/print.svg, for example. See Overriding Embedded Resources.

Creating your own icon pack

An icon pack needs no special attributes or base classes. To build one:

1. Create a .NET class library in C# or VB.NET.
2. Add the icon files to a folder named Resources. resource.wx serves .svg, .png, .gif, .jpg/.jpeg and .bmp files.
3. Set the Build Action of every icon to Embedded Resource.
4. Optionally, add a static class with a constant per icon, as the packs above do, for use in code.

Reference the library from your application, and its icons show up in the ImageSource editor next to the other packs. The quickest start is to copy one of the packs in the wisej-extensions repository and replace its Resources folder.