Optris.Icons.Avalonia

Optris.Icons.Avalonia

Optris-maintained fork. The original Projektanker.Icons.Avalonia is unmaintained — Projektanker GmbH has been dissolved and PRs to the upstream repo will not be reviewed. Optris GmbH has adopted this project to keep it alive for the Avalonia community, starting with an Avalonia 12 port.

Published to NuGet as Optris.Icons.Avalonia, Optris.Icons.Avalonia.FontAwesome, and Optris.Icons.Avalonia.MaterialDesign. The C# namespace has been renamed from Projektanker.Icons.Avalonia to Optris.Icons.Avalonia (the Projektanker name was misleading post-dissolution). The XAML XML namespace URL https://github.com/projektanker/icons.avalonia is preserved as an opaque identifier so existing consumer XAML keeps working without changes.

Repository: https://github.com/Optris/Optris.Icons.Avalonia

A library to easily display icons in an Avalonia App.

NuGet

Name	Description	Version
Optris.Icons.Avalonia	Core library
Optris.Icons.Avalonia.FontAwesome	Font Awesome 6 Free
Optris.Icons.Avalonia.MaterialDesign	Material Design Icons

Icon providers

Usage

A full example is available in the Demo project.

1. Register icon providers on app start up

Register the icon provider(s) with the IconProvider.Current.

class Program
{
    // Initialization code. Don't use any Avalonia, third-party APIs or any
    // SynchronizationContext-reliant code before AppMain is called: things aren't initialized
    // yet and stuff might break.
    public static void Main(string[] args)
    {
        BuildAvaloniaApp()
            .StartWithClassicDesktopLifetime(args);
    }

    // Avalonia configuration, don't remove; also used by visual designer.
    public static AppBuilder BuildAvaloniaApp()
    {
        IconProvider.Current
            .Register<FontAwesomeIconProvider>()
            .Register<MaterialDesignIconProvider>();

        return AppBuilder.Configure<App>()
            .UsePlatformDetect()
            .LogToTrace();
    }
}

2. Add xml namespace

Add xmlns:i="https://github.com/projektanker/icons.avalonia" to your view.

3. Use the icon

Standalone

<i:Icon Value="fa-brands fa-anchor" />

Attached to ContentControl (e.g. Button)

<Button i:Attached.Icon="fa-brands fa-anchor" />

Attached to MenuItem

<MenuItem Header="About" i:MenuItem.Icon="fa-solid fa-circle-info" />

Custom icon size

<i:Icon Value="fa-brands fa-anchor" FontSize="24" />

Animated

<i:Icon Value="fa-spinner" Animation="Pulse" />
<i:Icon Value="fa-sync" Animation="Spin" />

As an Image source

<Image>
  <Image.Source>
    <i:IconImage Value="fa-brands fa-anchor" Brush="(defaults to black)" />
  </Image.Source>
</Image>

Done

Implement your own Icon Provider

Just implement the IIconProvider interface:

namespace Optris.Icons.Avalonia
{
    /// <summary>
    /// Represents an icon reader.
    /// </summary>
    public interface IIconReader
    {
        /// <summary>
        /// Gets the model of the requested icon.
        /// </summary>
        /// <param name="value">The value specifying the icon to return it's model from.</param>
        /// <returns>The model of the icon.</returns>
        /// <exception cref="System.Collections.Generic.KeyNotFoundException">
        /// The icon associated with the specified <paramref name="value"/> does not exists.
        /// </exception>
        IconModel GetIcon(string value);
    }

    /// <summary>
    /// Represents an icon provider.
    /// </summary>
    public interface IIconProvider : IIconReader
    {
        /// <summary>
        /// Gets the prefix of the <see cref="IIconProvider"/>.
        /// </summary>
        string Prefix { get; }
    }
}

and register it with the IIconProviderContainer:

IconProvider.Current.Register<MyCustomIconProvider>()

or

IIconProvider provider = new MyCustomIconProvider(/* custom ctor arguments */);
IconProvider.Current.Register(provider);

The IIconProvider.Prefix property has to be unique within all registered providers. It is used to select the right provider. E.g. FontAwesomeIconProvider's prefix is fa.

Releasing a new version

The major version tracks Avalonia (e.g. 12.x.y for Avalonia 12). Minor and patch versions are for library changes.

1. Tag the release: git tag -a v12.0.1 -m "v12.0.1"
2. Push the tag: git push origin v12.0.1

The release workflow extracts the version from the tag, packs all three packages with it, and publishes to nuget.org. No need to edit version numbers in source files.