Umble.Umbraco.UmbleIcons 17.0.0

Umble Icons

Umble Icons adds icon selection and inline SVG rendering to Umbraco 17.

The NuGet package ID is Umble.Umbraco.UmbleIcons. Version 17.0.0 targets Umbraco 17 and .NET 10.

The package code is MIT licensed. Font Awesome Free 7.3.1 is bundled under the Font Awesome Free licence (icons: CC BY 4.0). Its licence file is included at App_Plugins/Umble.Icons/font-awesome/LICENSE.txt. Paid icons stay in the site that holds the licence. They are not part of this package.

What a site gets

• A dashboard under Settings → Umble Icons.
• An Umble Icon property editor with a compact selection summary. A searchable dialog shows each icon once, with library/family/style filters and a preview of its available styles. Multiple selections stay ordered and are confirmed together. Optional Appearance controls for colour, size, rotation, flip, animation, and duotone stay off until the data type allows them.
• On a document or element type, the header icon can choose an Umbraco icon or an Umble icon.
• Typed Razor values. A single selection is UmbleIcon?. Multiple selection is IReadOnlyList<UmbleIcon>.
• IUmbleIconRenderer writes the matching SVG inline.
• The Content Delivery API returns the same reference, plus an svg string when the file can be found.

Native backoffice icons load on demand. Umble does not download or register the entire installed icon collection during startup; repeated displayed icons share a request, and loading is limited to four concurrent requests. Server catalogue initialization is deferred until an icon or catalogue operation needs it.

Saved value

The property is stored on Umbraco.Plain.String:

{
  "schemaVersion": 1,
  "icons": [
    {
      "provider": "font-awesome",
      "name": "house",
      "variant": "fas"
    }
  ]
}

provider identifies the registered icon library. variant is that library's style ID; for Font Awesome it is a prefix such as fas or facr. Colour, size, rotation, flip, animation, and secondary colour are optional fields on each icon. An empty value means nothing is selected.

Other icon libraries

The picker and renderer use IUmbleIconProvider implementations. A site can register another singleton provider to supply its own searchable metadata, readable style labels and SVGs; the saved reference format remains the same. Font Awesome is included. Material and Lucide adapters are not bundled.

The interface is in Umble.Icons.Features.Catalogue.Services; register an implementation with builder.Services.AddSingleton<IUmbleIconProvider, MyLibraryIconProvider>(). See docs/icon-providers.md in the source repository for the full contract and grouped browse API.

Razor

@using Umble.Icons.Features.PropertyEditor.Models
@using Umble.Icons.Features.Rendering.Services
@inject IUmbleIconRenderer IconRenderer

@IconRenderer.Render(Model.Icon)

When the data type allows multiple icons, render the list:

@foreach (UmbleIcon icon in Model.Icons)
{
    @IconRenderer.Render(icon)
}

Extra icons

Font Awesome Free is bundled. A site can add more icons in any of these ways:

• Set UmbleIcons:FontAwesomeKitPackage to an npm package such as @fortawesome/fontawesome-pro, and install it with that site's Font Awesome token. Publish copies the metadata and SVGs into the deployed site.
• Set UmbleIcons:FontAwesomeKitPath to a Kit folder or .zip outside the Umble package.
• Put a svgs-full folder in the site project. Place metadata/icons.json or metadata/icons.yml beside it when labels and search terms are available.

A package name is used instead of a path when both are set. The svgs-full folder is loaded as well. Icon files belong to the site repository or that environment, not to this package.

Install a paid package in the site project directory, where its node_modules folder can be found. Configure your Font Awesome npm registry and token using Font Awesome's package setup instructions, keeping tokens out of source control. For example, after that registry configuration:

npm install @fortawesome/fontawesome-pro

Then set the package name in the site's configuration:

{
  "UmbleIcons": {
    "FontAwesomeKitPackage": "@fortawesome/fontawesome-pro"
  }
}

For Pro+ icons, install your account's Kit package and configure that exact package name instead. The all-inclusive @fortawesome/fontawesome-pro package contains Pro families; Pro+ icons are supplied through Kit packages. Only stock Kit icons are currently supported; uploaded custom icons remain a later feature. See Font Awesome's package options.

Publishing reads appsettings.json, the hosting environment's settings, then appsettings.Local.json, followed by the UmbleIcons__FontAwesomeKitPackage environment/MSBuild override. Comments and trailing commas are supported. The publish environment defaults to Production; set UmbleIconsPublishEnvironment explicitly when deploying elsewhere:

dotnet publish --configuration Release --property:UmbleIconsPublishEnvironment=Staging

If no explicit environment is supplied, DOTNET_ENVIRONMENT then ASPNETCORE_ENVIRONMENT are considered before the Production default. Build configuration names such as Release do not select hosting settings. The npm helper requires Node on the publishing machine and copies only the installed metadata, SVG folders, and licence into umbraco/Data/UmbleIcons/font-awesome-kit. Missing packages or invalid settings fail the publish with an explanation.

The site-root svgs-full option and its metadata/icons.json or metadata/icons.yml publish automatically without Node. An external FontAwesomeKitPath must be made available at its configured path on the deployed host; external folders and ZIP files are not automatically copied.

Delivery API

Enable the Delivery API on the site. An Umble icon property is returned as an object with provider, name, variant, the optional style fields, and svg. Multiple selection returns an array. An empty single selection is null.