Fluentui Blazor

Fluent UI Blazor — Consumer Usage Guide

This skill teaches how to correctly use the Microsoft.FluentUI.AspNetCore.Components (version 4) NuGet package in Blazor applications.

Critical Rules

1. No manual <script> or <link> tags needed

The library auto-loads all CSS and JS via Blazor's static web assets and JS initializers. Never tell users to add `<script>` or `<link>` tags for the core library.

2. Providers are mandatory for service-based components

These provider components MUST be added to the root layout (e.g. MainLayout.razor) for their corresponding services to work. Without them, service calls fail silently (no error, no UI).

<FluentToastProvider />
<FluentDialogProvider />
<FluentMessageBarProvider />
<FluentTooltipProvider />
<FluentKeyCodeProvider />

3. Service registration in Program.cs

builder.Services.AddFluentUIComponents();

// Or with configuration:
builder.Services.AddFluentUIComponents(options =>
{
    options.UseTooltipServiceProvider = true;  // default: true
    options.ServiceLifetime = ServiceLifetime.Scoped; // default
});

ServiceLifetime rules:

• ServiceLifetime.Scoped — for Blazor Server / Interactive (default)
• ServiceLifetime.Singleton — for Blazor WebAssembly standalone
• ServiceLifetime.Transient — throws `NotSupportedException`

4. Icons require a separate NuGet package

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

Usage with a @using alias:

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

<FluentIcon Value="@(Icons.Regular.Size24.Save)" />
<FluentIcon Value="@(Icons.Filled.Size20.Delete)" Color="@Color.Error" />

Pattern: Icons.[Variant].[Size].[Name]

• Variants: Regular, Filled
• Sizes: Size12, Size16, Size20, Size24, Size28, Size32, Size48

Custom image: Icon.FromImageUrl("/path/to/image.png")

Never use string-based icon names — icons are strongly-typed classes.

5. List component binding model

FluentSelect<TOption>, FluentCombobox<TOption>, FluentListbox<TOption>, and FluentAutocomplete<TOption> do NOT work like <InputSelect>. They use:

• Items — the data source (IEnumerable<TOption>)
• OptionText — Func<TOption, string?> to extract display text
• OptionValue — Func<TOption, string?> to extract the value string
• SelectedOption / SelectedOptionChanged — for single selection binding
• SelectedOptions / SelectedOptionsChanged — for multi-selection binding

<FluentSelect Items="@countries"
              OptionText="@(c => c.Name)"
              OptionValue="@(c => c.Code)"
              @bind-SelectedOption="@selectedCountry"
              Label="Country" />

NOT like this (wrong pattern):

@* WRONG — do not use InputSelect pattern *@
<FluentSelect @bind-Value="@selectedValue">
    <option value="1">One</option>
</FluentSelect>

6. FluentAutocomplete specifics

• Use ValueText (NOT Value — it's obsolete) for the search input text
• OnOptionsSearch is the required callback to filter options
• Default is Multiple="true"

<FluentAutocomplete TOption="Person"
                    OnOptionsSearch="@OnSearch"
                    OptionText="@(p => p.FullName)"
                    @bind-SelectedOptions="@selectedPeople"
                    Label="Search people" />

@code {
    private void OnSearch(OptionsSearchEventArgs<Person> args)
    {
        args.Items = allPeople.Where(p =>
            p.FullName.Contains(args.Text, StringComparison.OrdinalIgnoreCase));
    }
}

7. Dialog service pattern

Do NOT toggle visibility of `<FluentDialog>` tags. The service pattern is:

1. Create a content component implementing IDialogContentComponent<TData>:

public partial class EditPersonDialog : IDialogContentComponent<Person>
{
    [Parameter] public Person Content { get; set; } = default!;

    [CascadingParameter] public FluentDialog Dialog { get; set; } = default!;

    private async Task SaveAsync()
    {
        await Dialog.CloseAsync(Content);
    }

    private async Task CancelAsync()
    {
        await Dialog.CancelAsync();
    }
}

2. Show the dialog via IDialogService:

[Inject] private IDialogService DialogService { get; set; } = default!;

private async Task ShowEditDialog()
{
    var dialog = await DialogService.ShowDialogAsync<EditPersonDialog, Person>(
        person,
        new DialogParameters
        {
            Title = "Edit Person",
            PrimaryAction = "Save",
            SecondaryAction = "Cancel",
            Width = "500px",
            PreventDismissOnOverlayClick = true,
        });

    var result = await dialog.Result;
    if (!result.Cancelled)
    {
        var updatedPerson = result.Data as Person;
    }
}

For convenience dialogs:

await DialogService.ShowConfirmationAsync("Are you sure?", "Yes", "No");
await DialogService.ShowSuccessAsync("Done!");
await DialogService.ShowErrorAsync("Something went wrong.");

8. Toast notifications

[Inject] private IToastService ToastService { get; set; } = default!;

ToastService.ShowSuccess("Item saved successfully");
ToastService.ShowError("Failed to save");
ToastService.ShowWarning("Check your input");
ToastService.ShowInfo("New update available");

FluentToastProvider parameters: Position (default TopRight), Timeout (default 7000ms), MaxToastCount (default 4).

9. Design tokens and themes work only after render

Design tokens rely on JS interop. Never set them in `OnInitialized` — use OnAfterRenderAsync.

<FluentDesignTheme Mode="DesignThemeModes.System"
                   OfficeColor="OfficeColor.Teams"
                   StorageName="mytheme" />

10. FluentEditForm vs EditForm

FluentEditForm is only needed inside FluentWizard steps (per-step validation). For regular forms, use standard EditForm with Fluent form components:

<EditForm Model="@model" OnValidSubmit="HandleSubmit">
    <DataAnnotationsValidator />
    <FluentTextField @bind-Value="@model.Name" Label="Name" Required />
    <FluentSelect Items="@options"
                  OptionText="@(o => o.Label)"
                  @bind-SelectedOption="@model.Category"
                  Label="Category" />
    <FluentValidationSummary />
    <FluentButton Type="ButtonType.Submit" Appearance="Appearance.Accent">Save</FluentButton>
</EditForm>

Use FluentValidationMessage and FluentValidationSummary instead of standard Blazor validation components for Fluent styling.

Reference files

For detailed guidance on specific topics, see:

• Setup and configuration
• Layout and navigation
• Data grid
• Theming

FluentDataGrid

FluentDataGrid<TGridItem> is a strongly-typed generic component for displaying tabular data.

Basic Usage

<FluentDataGrid Items="@people" TGridItem="Person">
    <PropertyColumn Property="@(p => p.Name)" Sortable="true" />
    <PropertyColumn Property="@(p => p.Email)" />
    <PropertyColumn Property="@(p => p.BirthDate)" Format="yyyy-MM-dd" />
    <TemplateColumn Title="Actions">
        <FluentButton OnClick="@(() => Edit(context))">Edit</FluentButton>
    </TemplateColumn>
</FluentDataGrid>

Critical: Columns are child components, NOT properties. Use PropertyColumn, TemplateColumn, and SelectColumn within the grid.

Column Types

PropertyColumn

Binds to a property expression. Auto-derives title from property name or [Display] attribute.

<PropertyColumn Property="@(p => p.Name)" Sortable="true" />
<PropertyColumn Property="@(p => p.Price)" Format="C2" Title="Unit Price" />
<PropertyColumn Property="@(p => p.Category)" Comparer="@StringComparer.OrdinalIgnoreCase" />

Parameters: Property (required), Format, Title, Sortable, SortBy, Comparer, IsDefaultSortColumn, InitialSortDirection, Class, Tooltip.

TemplateColumn

Full custom rendering via render fragment. context is the TGridItem.

<TemplateColumn Title="Status" SortBy="@statusSort">
    <FluentBadge Appearance="Appearance.Accent"
                 BackgroundColor="@(context.IsActive ? "green" : "red")">
        @(context.IsActive ? "Active" : "Inactive")
    </FluentBadge>
</TemplateColumn>

SelectColumn

Checkbox selection column.

<SelectColumn TGridItem="Person"
              SelectMode="DataGridSelectMode.Multiple"
              @bind-SelectedItems="@selectedPeople" />

Modes: DataGridSelectMode.Single, DataGridSelectMode.Multiple.

Data Sources

Two mutually exclusive approaches:

In-memory (IQueryable)

<FluentDataGrid Items="@people.AsQueryable()" TGridItem="Person">
    ...
</FluentDataGrid>

Server-side / Custom (ItemsProvider)

<FluentDataGrid ItemsProvider="@peopleProvider" TGridItem="Person">
    ...
</FluentDataGrid>

@code {
    private GridItemsProvider<Person> peopleProvider = async request =>
    {
        var result = await PeopleService.GetPeopleAsync(
            request.StartIndex,
            request.Count ?? 50,
            request.GetSortByProperties().FirstOrDefault());

        return GridItemsProviderResult.From(result.Items, result.TotalCount);
    };
}

EF Core Adapter

// Program.cs
builder.Services.AddDataGridEntityFrameworkAdapter();

<FluentDataGrid Items="@dbContext.People" TGridItem="Person">
    ...
</FluentDataGrid>

Pagination

<FluentDataGrid Items="@people" Pagination="@pagination" TGridItem="Person">
    ...
</FluentDataGrid>

<FluentPaginator State="@pagination" />

@code {
    private PaginationState pagination = new() { ItemsPerPage = 10 };
}

Virtualization

For large datasets, enable virtualization:

<FluentDataGrid Items="@people" Virtualize="true" ItemSize="46" TGridItem="Person">
    ...
</FluentDataGrid>

ItemSize is the estimated row height in pixels (default varies). Important for scroll position calculations.

Key Parameters

Sorting

<PropertyColumn Property="@(p => p.Name)" Sortable="true" IsDefaultSortColumn="true"
                InitialSortDirection="SortDirection.Ascending" />

Or with a custom sort:

<TemplateColumn Title="Full Name" SortBy="@(GridSort<Person>.ByAscending(p => p.LastName).ThenAscending(p => p.FirstName))">
    @context.LastName, @context.FirstName
</TemplateColumn>

Layout and Navigation

Layout Components

FluentLayout

Root layout container. Use as the outermost structural component.

<FluentLayout Orientation="Orientation.Vertical">
    <FluentHeader>...</FluentHeader>
    <FluentBodyContent>...</FluentBodyContent>
    <FluentFooter>...</FluentFooter>
</FluentLayout>

FluentHeader / FluentFooter

Sticky header and footer sections within FluentLayout.

<FluentHeader Height="50">
    <FluentStack Orientation="Orientation.Horizontal" HorizontalAlignment="HorizontalAlignment.SpaceBetween">
        <span>App Title</span>
        <FluentButton>Settings</FluentButton>
    </FluentStack>
</FluentHeader>

FluentBodyContent

Main scrollable content area within FluentLayout.

FluentStack

Flexbox container for horizontal or vertical layouts.

<FluentStack Orientation="Orientation.Horizontal"
             HorizontalGap="10"
             VerticalGap="10"
             HorizontalAlignment="HorizontalAlignment.Center"
             VerticalAlignment="VerticalAlignment.Center"
             Wrap="true"
             Width="100%">
    <FluentButton>One</FluentButton>
    <FluentButton>Two</FluentButton>
</FluentStack>

Parameters: Orientation, HorizontalGap, VerticalGap, HorizontalAlignment, VerticalAlignment, Wrap, Width.

FluentGrid / FluentGridItem

12-column responsive grid system.

<FluentGrid Spacing="3" Justify="JustifyContent.Center" AdaptiveRendering="true">
    <FluentGridItem xs="12" sm="6" md="4" lg="3">
        Card 1
    </FluentGridItem>
    <FluentGridItem xs="12" sm="6" md="4" lg="3">
        Card 2
    </FluentGridItem>
</FluentGrid>

Size parameters (xs, sm, md, lg, xl, xxl) represent column spans out of 12. Use AdaptiveRendering="true" to hide items that don't fit.

FluentMainLayout (convenience)

Pre-composed layout with header, nav menu, and body area.

<FluentMainLayout Header="@header"
                  SubHeader="@subheader"
                  NavMenuContent="@navMenu"
                  Body="@body"
                  HeaderHeight="50"
                  NavMenuWidth="250"
                  NavMenuTitle="Navigation" />

Navigation Components

FluentNavMenu

Collapsible navigation menu with keyboard support.

<FluentNavMenu Width="250"
               Collapsible="true"
               @bind-Expanded="@menuExpanded"
               Title="Main navigation"
               CollapsedChildNavigation="true"
               Margin="4px 0">
    <FluentNavLink Href="/" Icon="@(Icons.Regular.Size20.Home)" Match="NavLinkMatch.All">
        Home
    </FluentNavLink>
    <FluentNavLink Href="/counter" Icon="@(Icons.Regular.Size20.NumberSymbol)">
        Counter
    </FluentNavLink>
    <FluentNavGroup Title="Admin" Icon="@(Icons.Regular.Size20.Shield)" @bind-Expanded="@adminExpanded">
        <FluentNavLink Href="/admin/users">Users</FluentNavLink>
        <FluentNavLink Href="/admin/roles">Roles</FluentNavLink>
    </FluentNavGroup>
</FluentNavMenu>

Key parameters:

• Width — width in pixels (40px when collapsed)
• Collapsible — enables expand/collapse toggle
• Expanded / ExpandedChanged — bindable collapse state
• CollapsedChildNavigation — shows flyout menus for groups when collapsed
• CustomToggle — for mobile hamburger button patterns
• Title — aria-label for accessibility

FluentNavGroup

Expandable group within a nav menu.

<FluentNavGroup Title="Settings"
                Icon="@(Icons.Regular.Size20.Settings)"
                @bind-Expanded="@settingsExpanded"
                Gap="2">
    <FluentNavLink Href="/settings/general">General</FluentNavLink>
    <FluentNavLink Href="/settings/profile">Profile</FluentNavLink>
</FluentNavGroup>

Parameters: Title, Expanded/ExpandedChanged, Icon, IconColor, HideExpander, Gap, MaxHeight, TitleTemplate.

FluentNavLink

Navigation link with active state tracking.

<FluentNavLink Href="/page"
               Icon="@(Icons.Regular.Size20.Document)"
               Match="NavLinkMatch.Prefix"
               Target="_blank"
               Disabled="false">
    Page Title
</FluentNavLink>

Parameters: Href, Target, Match (NavLinkMatch.Prefix default, or All), ActiveClass, Icon, IconColor, Disabled, Tooltip.

All nav components inherit from FluentNavBase which provides: Icon, IconColor, CustomColor, Disabled, Tooltip.

FluentBreadcrumb / FluentBreadcrumbItem

<FluentBreadcrumb>
    <FluentBreadcrumbItem Href="/">Home</FluentBreadcrumbItem>
    <FluentBreadcrumbItem Href="/products">Products</FluentBreadcrumbItem>
    <FluentBreadcrumbItem>Current Page</FluentBreadcrumbItem>
</FluentBreadcrumb>

FluentTab / FluentTabs

<FluentTabs @bind-ActiveTabId="@activeTab">
    <FluentTab Id="tab1" Label="Details">
        Details content
    </FluentTab>
    <FluentTab Id="tab2" Label="History">
        History content
    </FluentTab>
</FluentTabs>

Setup and Configuration

NuGet Packages

Program.cs Registration

builder.Services.AddFluentUIComponents();

Configuration Options (LibraryConfiguration)

ServiceLifetime by hosting model

MainLayout.razor Template

@inherits LayoutComponentBase

<FluentLayout>
    <FluentHeader Height="50">
        My App
    </FluentHeader>

    <FluentStack Orientation="Orientation.Horizontal" HorizontalGap="0" Style="height: 100%;">
        <FluentNavMenu Width="250" Collapsible="true" Title="Navigation">
            <FluentNavLink Href="/" Icon="@(Icons.Regular.Size20.Home)" Match="NavLinkMatch.All">Home</FluentNavLink>
            <FluentNavLink Href="/counter" Icon="@(Icons.Regular.Size20.NumberSymbol)">Counter</FluentNavLink>
            <FluentNavGroup Title="Settings" Icon="@(Icons.Regular.Size20.Settings)">
                <FluentNavLink Href="/settings/general">General</FluentNavLink>
                <FluentNavLink Href="/settings/profile">Profile</FluentNavLink>
            </FluentNavGroup>
        </FluentNavMenu>

        <FluentBodyContent>
            <FluentStack Orientation="Orientation.Vertical" Style="padding: 1rem;">
                @Body
            </FluentStack>
        </FluentBodyContent>
    </FluentStack>
</FluentLayout>

@* Required providers — place after FluentLayout *@
<FluentToastProvider />
<FluentDialogProvider />
<FluentMessageBarProvider />
<FluentTooltipProvider />
<FluentKeyCodeProvider />

@* Theme — place at root *@
<FluentDesignTheme Mode="DesignThemeModes.System"
                   OfficeColor="OfficeColor.Teams"
                   StorageName="mytheme" />

Or use the convenience component:

<FluentMainLayout Header="@header"
                  NavMenuContent="@navMenu"
                  Body="@body"
                  HeaderHeight="50"
                  NavMenuWidth="250"
                  NavMenuTitle="Navigation" />

@code {
    private RenderFragment header = @<span>My App</span>;
    private RenderFragment navMenu = @<div>
        <FluentNavLink Href="/">Home</FluentNavLink>
    </div>;
    private RenderFragment body = @<div>@Body</div>;
}

_Imports.razor

Add this to your _Imports.razor:

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

Static Web Assets

No manual <link> or <script> tags are needed. The library uses:

• CSS: reboot.css (normalization) + component-scoped CSS — auto-loaded via static web assets
• JS: lib.module.js — auto-loaded via Blazor's JS initializer system
• Component-specific JS (e.g. DataGrid, Autocomplete) — lazy-loaded on demand

All served from _content/Microsoft.FluentUI.AspNetCore.Components/.

Services Registered

Services automatically registered by AddFluentUIComponents():

Theming

FluentDesignTheme (recommended)

The primary theming component. Place it at the root of your app.

<FluentDesignTheme Mode="DesignThemeModes.System"
                   OfficeColor="OfficeColor.Teams"
                   StorageName="mytheme" />

Parameters

Two-way binding

<FluentDesignTheme @bind-Mode="@themeMode"
                   @bind-OfficeColor="@officeColor"
                   @bind-CustomColor="@customColor"
                   StorageName="mytheme" />

<FluentSelect Items="@(Enum.GetValues<DesignThemeModes>())"
              @bind-SelectedOption="@themeMode"
              OptionText="@(m => m.ToString())" />

@code {
    private DesignThemeModes themeMode = DesignThemeModes.System;
    private OfficeColor? officeColor = OfficeColor.Teams;
    private string? customColor;
}

Important: JS interop dependency

FluentDesignTheme uses JavaScript interop internally. It will NOT work during server-side pre-rendering. If you need to react to theme changes:

// Use OnAfterRenderAsync, NOT OnInitialized
protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (firstRender)
    {
        // Safe to interact with design tokens here
    }
}

FluentDesignSystemProvider (advanced)

For scoping design tokens to a subtree of the component tree. Provides 50+ CSS custom properties.

<FluentDesignSystemProvider AccentBaseColor="#0078D4"
                            NeutralBaseColor="#808080"
                            BaseLayerLuminance="0.95">
    <FluentButton Appearance="Appearance.Accent">Themed Button</FluentButton>
</FluentDesignSystemProvider>

Design Token Classes (DI-based, advanced)

For programmatic token control via dependency injection. Each token is a generated service.

@inject AccentBaseColor AccentBaseColor

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (firstRender)
    {
        // Set token for a specific element
        await AccentBaseColor.SetValueFor(myElement, "#FF0000".ToSwatch());

        // Read token value
        var currentColor = await AccentBaseColor.GetValueFor(myElement);

        // Remove override
        await AccentBaseColor.DeleteValueFor(myElement);
    }
}

Available DesignThemeModes

• DesignThemeModes.Light — light theme
• DesignThemeModes.Dark — dark theme
• DesignThemeModes.System — follows OS preference

Available OfficeColor presets

Teams, Word, Excel, PowerPoint, Outlook, OneNote, Loop, Planner, SharePoint, Stream, Sway, Viva, VivaEngage, VivaInsights, VivaLearning, VivaTopics.