FluentUI.Blazor v5.rc1

Announcing Fluent UI Blazor v5 RC1 — A New Era for Fluent UI in Blazor

Today we are thrilled to publish the first Release Candidate of Fluent UI Blazor library v5! This major release marks a significant evolution for the library, bringing a new foundation built on top of the latest Fluent UI Web Components, a powerful new FluentLayout component, a game-changing Default Values system, and first-class Localization support. And lots of new components, each more powerful than the last.

Let’s walk through what’s new and why we think v5 is the best version of Fluent UI Blazor yet.

A New Foundation: Fluent UI Web Components 3.x

Version 5 represents a fundamental shift in the underlying rendering layer. The library has moved away from the previous FAST-based web components to the new Fluent UI Web Components 3.x — the very same components that power Microsoft’s own products like Microsoft 365, Teams, and Windows 11.

What does this mean for you?

• Pixel-perfect Fluent 2 design — Your Blazor components now render with the exact same look and feel as Microsoft’s own products. No more subtle visual discrepancies.
• Better performance — The new web components are lighter and more efficient. The reduced JavaScript footprint leads to faster initial load times and smoother interactions.
• Improved accessibility — Accessibility is a first-class citizen in the new web component layer, delivering WCAG 2.1 AA compliance out of the box.
• Reduced bundle size — By removing the legacy FAST dependency, the overall package size has been significantly trimmed.

What changes in your code?

For most existing components, the migration is seamless — your Blazor markup stays the same. The library still exposes the same FluentButton, FluentSelect, and other components you already know. Under the hood, these components now render the new Fluent UI Web Components.

However, we have sometimes been forced to make significant changes to certain components: in the name or in the arguments. You can consult this migration page to see all these changes.

In addition, we are also providing a dedicated MCP Server for this new library. It will be your new assistant for migration and development on a daily basis.

No additional JavaScript or CSS file references are required — the library handles everything automatically. The web component scripts are included and loaded by the library itself.

Getting started

Install the NuGet packages:

dotnet add package Microsoft.FluentUI.AspNetCore.Components --prerelease
dotnet add package Microsoft.FluentUI.AspNetCore.Components.Icons

Add the namespace to your _Imports.razor:

@using Microsoft.FluentUI.AspNetCore.Components
@using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons

Register the services in Program.cs:

builder.Services.AddFluentUIComponents();

And add the provider component at the end of your MainLayout.razor:

@* Add all FluentUI Blazor Providers *@
<FluentProviders />

That’s it. You’re ready to build with Fluent UI v5.

The New FluentLayout Component

Version 5 introduces a completely redesigned FluentLayout component that serves as the structural backbone for your application. Rather than manually composing CSS Grid or Flexbox layouts, FluentLayout provides a declarative, area-based system for building full-page layouts with a fixed header, navigation panel, content area, and footer.

Area-based layout

The key concept is FluentLayoutItem with a LayoutArea — you declare where each piece of content should go, and the layout engine handles the rest:

@inherits LayoutComponentBase

<FluentLayout>

    <!-- Header -->
    <FluentLayoutItem Area="@LayoutArea.Header">
        <FluentStack VerticalAlignment="VerticalAlignment.Center">
            <FluentLayoutHamburger />
            <FluentText Weight="TextWeight.Bold"
                        Size="TextSize.Size400">
                My Application
            </FluentText>
            <FluentSpacer />
        </FluentStack>
    </FluentLayoutItem>

    <!-- Navigation -->
    <FluentLayoutItem Area="@LayoutArea.Navigation"
                      Width="250px">
        <NavMenu />
    </FluentLayoutItem>

    <!-- Content -->
    <FluentLayoutItem Area="@LayoutArea.Content"
                      Padding="@Padding.All3">
        @Body
    </FluentLayoutItem>

    <!-- Footer -->
    <FluentLayoutItem Area="@LayoutArea.Footer">
        Powered by Microsoft Fluent UI Blazor
    </FluentLayoutItem>

</FluentLayout>

<FluentProviders />

Built-in hamburger menu

Notice the FluentLayoutHamburger component in the header. This renders a hamburger button that automatically toggles the navigation panel — complete with smooth animations and responsive behavior. No extra JavaScript needed.

Why this matters

• Consistent structure — Every page in your application follows the same layout contract. No more layout drift.
• Responsive by design — The navigation panel collapses automatically on smaller screens.
• Typed areas — Using LayoutArea.Header, LayoutArea.Navigation, LayoutArea.Content, and LayoutArea.Footer ensures you can’t misplace content.
• Customizable sizing — Control the width of the navigation panel, padding of content areas, and more through simple parameters.

For more layout examples, visit the FluentLayout documentation.

Default Values — A Game Changer

One of the most important and eagerly awaited features in v5 is the Default Values system. This powerful mechanism lets you define global default parameter values for any Fluent UI component — once — and have them applied everywhere in your application.

The problem it solves

In v4 and earlier, if you wanted all your buttons to use a specific appearance, you had to set it on every single instance:

<!-- Repetitive and error-prone -->
<FluentButton Appearance="ButtonAppearance.Primary">Save</FluentButton>
<FluentButton Appearance="ButtonAppearance.Primary">Submit</FluentButton>
<FluentButton Appearance="ButtonAppearance.Primary">Confirm</FluentButton>

This was tedious, error-prone, and a maintenance nightmare. Changing a design decision meant touching potentially hundreds of files.

The solution

With v5, configure default values globally in your Program.cs:

builder.Services.AddFluentUIComponents(config =>
{
    // Set default values for FluentButton component
    config.DefaultValues.For<FluentButton>()
          .Set(p => p.Appearance, ButtonAppearance.Primary);
    config.DefaultValues.For<FluentButton>()
          .Set(p => p.Shape, ButtonShape.Circular);
});

Now every FluentButton in your application automatically uses Primary appearance and Circular shape — unless you explicitly override it on a specific instance:

<!-- Uses global defaults (Primary + Circular) -->
<FluentButton>Save</FluentButton>

<!-- Override just the appearance for this instance -->
<FluentButton Appearance="ButtonAppearance.Outline">Cancel</FluentButton>

Key benefits

This feature is particularly powerful for organizations that need consistent component styling across large applications or shared design systems.

Localization Support

Version 5 introduces a built-in Localization system that makes it easy to translate all component-internal strings — button labels, ARIA attributes, accessibility texts, and more — into any language.

How it works

The library ships with English strings by default. To localize components, implement the IFluentLocalizer interface:

using Microsoft.FluentUI.AspNetCore.Components;

public class CustomFluentLocalizer : IFluentLocalizer
{
    public string this[string key, params object[] arguments]
    {
        get
        {
            return key switch
            {
                "SomeKey" => "Your Custom Translation",
                "AnotherKey" => string.Format("Another Translation {0}", arguments),

                // Fallback to English if no translation is found
                _ => IFluentLocalizer.GetDefault(key, arguments),
            };
        }
    }
}

Register it in Program.cs:

builder.Services.AddFluentUIComponents(config =>
    config.Localizer = new CustomFluentLocalizer());

You can also use your embedded resources (.resx) for multilingual support. Everything is documented on our website.

Try It Now

This is a Release Candidate — the API surface is stabilized, but we’re counting on the community to help us identify remaining issues before the final release. Please file issues on GitHub, and don’t hesitate to contribute.

Several components do not yet exist, but we are working on them for the next version: dev-v5 - TODO List

Thank you to everyone who has contributed, tested, and provided feedback throughout the v5 development cycle. We’re incredibly excited about this release and can’t wait to see what you build with it!

Happy Blazoring!
The Fluent UI Blazor team