What’s new in the Microsoft Fluent UI library for Blazor versions 1.3 and 1.4

The FAST team and friends have been hard at work not only on Microsoft’s core Web Components platform, but also on Fluent UI integrations for Blazor. This post will give you an overview of what’s new and changed in versions 1.3 and 1.4 of the Microsoft Fluent UI Blazor library.

In short, the two big end-user additions (besides some bug fixes) are:

• Fluent UI System Icons support
• Design Token support

And repository and code changes:

• Add missing xml comments
• Add FocusAsync methods to FluentInputBase

Fluent UI System Icons support

The Fluent UI System Icons are a (still growing) collection of familiar, friendly, and modern icons from Microsoft. Currently, more than 2020 distinct icons are available in various sizes of filled and outlined versions. The collections consist of well over 11k icons in SVG format. All of them have been added to the library in an easy-to-use way by adding the <FluentIcon> component. Just putting this in your .razor page:

Will give you this:

Accessibility icon in the accent color

A couple of things to unwrap here on the parameters used:

• Name is a string. All names have been added as constants to make it easier to select an icon. IntelliSense will help you find the right one. It is also using the new .NET 6 EditorRequired feature. If you don’t pass a value for the Name, Visual Studio will point that out to you in design time and raise a compile error when building.
• Size is using an enum that holds all the possible valid sizes. Note that not all sizes are available for all icons. If you get an error at run-time, supply a different size or remove the parameter to fall back to the default size (IconSize.Size24).
• Filled is a bool to choose a filled (true) or a regular/outlined (false) version of an icon.

Other parameters (not shown in the example above) for this component are:

• UseAccentColor (bool). This parameter defaults to true and determines if the accent color is used for the fill or the outline when rendering the icon. When setting this to false, the icon will be rendered in black.
• NeutralCultureName (string). Some icons offer alternative versions for specific languages. By supplying the two-letter neutral language code, you can indicate that you would like to use that specific version of an icon. The component will fall back to rendering the original version if there is no language-specific version.
• Slot (string). With the slot parameter you can indicate where an icon needs to be rendered in the context of another component. For example, when combining a <FluentButton>with a <FluentIcon>, you can use the slot to put the icon in front of the button text:

Note that while the icon is positioned after the “Search” text in the markup, it will render before the button text because the slot=start. Here’s what it looks like:

Image of a button with an icon

The temporary demo site has a page to search through all the available icons and sizes.

In earlier and other libraries, icons are often included using fonts. This method has the disadvantage that the whole font needs to be downloaded even if you only use one icon. Instead, we stepped away from using that method in this library and opted for taking the SVG route. Because the icons are SVG files stored in the wwwroot folder in an RCL (Razor Class Library), they are treated like static files on the server. They don’t get downloaded until requested, and only the icons you are actually using will be downloaded.

Design Token support

The Fluent UI Web Components are built on FAST’s Adaptive UI technology, enabling design customization and personalization while automatically maintaining accessibility. This is accomplished through setting various “Design Tokens”. In previous versions of this library, the only way to manipulate the design tokens was through using the <FluentDesignSystemProvider> component. This Blazor component (and its underlying Web Component) exposed over 60 variables that could be used to change things like typography, color, sizes, UI spacing, etc. FAST was extended a while ago and now has a much more granular way of working with individual design tokens instead of just a design system provider model. See https://docs.microsoft.com/en-us/fluent-ui/web-components/design-system/design-tokens for more information on how Design Tokens work.

In total, there are now over 160 distinct tokens defined in the Adaptive UI model, and as of version 1.4 of this library, you can use all these in Blazor as well! The implementation has been in the works for multiple months, and we think the result is quite flexible. It allows for usage both from C# code as well as declaratively in your .razor pages. The two ways of working with design tokens are described below (taken from the repository readme):

Option 1: Using Design Tokens from C# code

Given the following .razor page fragment:

You can use Design Tokens to manipulate the styles from C# code as follows:

As seen in the code above (with the ref4.Element), it is possible to apply multiple tokens to the same component.

For Design Tokens that work with a color value, you must call the ToSwatch() extension method on a string value or use one of the Swatch constructors. This ensures the color uses a format that Design Tokens can handle. A Swatch has a lot of commonalities with the System.Drawing.Color struct. Instead of the values of the components being between 0 and 255, in a Swatch they are expressed as a value between 0 and 1.

⚠️ IMPORTANT

The Design Tokens are manipulated through JavaScript interop working with an ElementReference. There is no JavaScript element until after the component is rendered. This means you can only work with the Design Tokens from code after the component has been rendered in OnAfterRenderAsync and not in any earlier lifecycle methods.

Option 2: Using Design Tokens as components

The Design Tokens can also be used as components in a .razor page directly. It looks like this:

To make this work, a link must be created between the Design Token component and its child components. This is done with the BackReference="@Context" construct.

ℹ️ NOTE

Only one Design Token component at a time can be used this way. If you need to set more tokens, use the code approach as described in Option 1 above.

Besides these two new options, the original <FluentDesignSystemProvider> component is still there and can be used as always. There are no plans to remove this anytime soon.

XML Comments

All components and all component parameters now have XML comments. This means that tools that support this, like Visual Studio IntelliSense, will show you information about methods and parameters when editing your razor pages and code, making it a bit easier to discover and understand functionality:

Screenshot of IntelliSense in action

Add FocusAsync to FluentInputBase

It was not possible before to programmatically set focus to an <input> deriving component like the <FluentTextField> or <FluentNumberField>. The base class <FluentInputBase> has now been extended to expose this method.

Wrapping Up

We’re excited to bring these powerful new design token and icon capabilities to Blazor developers and can’t wait to see what you’ll build with them. As FAST and the Fluent UI Web Components evolve, we’ll continue to work hard to bring you more components, features, and improvements like these.