What's new for the Microsoft Fluent UI Blazor library 5.0 RC1

Today we are thrilled to publish the first Release Candidate of the 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, powerful new components, a game-changing Default Values system, and first-class Localization support. 

A New Foundation: Fluent UI Web Components 3

V5 represents a fundamental shift in the underlying rendering layer. The library has moved away from the previous FAST-based web components and now uses the new Fluent UI Web Components v3 — 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 quite 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 using the new Fluent UI Web Components.

However, because the web components are now aligned to the Fluent UI React components with regards to attribute names, we needed to make significant changes a lot of our components as well. We created a lot of documentation to help you migrate.

In addition, we are also providing a MCP Server for this version of the library. This will be your helpful 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 automatically by the library.

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 are now ready to start building your applications with the Fluent UI Blazor library v5.

The New FluentLayout Component

V5 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 a 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

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 earlier versions, if you wanted all your buttons to use a specific appearance, you had to set it on every single instance:

<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. Making a design change meant touching potentially hundreds of files.

The solution

With v5, you can configure default values globally in your Program.cs as follows:

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 the 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

• Single source of truth. Define your design decisions once, apply them everywhere.
• Easy branding. Switch your entire application’s look by changing a few lines in Program.cs.
• Explicit overrides. Any component instance can still override defaults with a local parameter.
• Strongly typed. The API uses lambda expressions — full IntelliSense, no magic strings.
• Maintainable. Changing a design decision no longer requires a massive find-and-replace.

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

Localization Support

V5 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. The component documentation pages give an overview of the strings that can be localized. The earlier mentioned MCP server can be of help there as well.

Try It Now

Resource	Link
Package available on Nuget	Microsoft.FluentUI.AspNetCore.Components --prerelease
Documentation	https://fluentui-blazor-v5.azurewebsites.net
GitHub (v5 branch)	https://github.com/microsoft/fluentui-blazor/tree/dev-v5
Migration guide	Migration to v5

Final remarks

This is our first Release Candidate. The API surface is fairly stabilized.

We are counting on the community to help us identify any remaining issues! Please file issue reports on GitHub (with ready-to-run reproduction code), and don’t hesitate to contribute.

Several components are still missing. We are currently working on those nd they will come with the next RC's. See the dev-v5 - TODO List for an overview

A big 'thank you' to everyone who has already contributed, tested, and provided feedback throughout the (long) v5 development cycle. We’re incredibly excited about this release and can’t wait to see what you build with it!