Fluentui Blazor

---
name: fluentui-blazor
description: >
  Guide for using the Microsoft Fluent UI Blazor component library
  (Microsoft.FluentUI.AspNetCore.Components NuGet package) in Blazor applications.
  Use this when the user is building a Blazor app with Fluent UI components,
  setting up the library, using FluentUI components like FluentButton, FluentDataGrid,
  FluentDialog, FluentToast, FluentNavMenu, FluentTextField, FluentSelect,
  FluentAutocomplete, FluentDesignTheme, or any component prefixed with "Fluent".
  Also use when troubleshooting missing providers, JS interop issues, or theming.
---

# 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).

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

### 3. Service registration in Program.cs

```csharp
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:

```razor
@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

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

**NOT** like this (wrong pattern):
```razor
@* 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"`

```razor
<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>`:

```csharp
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`:

```csharp
[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:
```csharp
await DialogService.ShowConfirmationAsync("Are you sure?", "Yes", "No");
await DialogService.ShowSuccessAsync("Done!");
await DialogService.ShowErrorAsync("Something went wrong.");
```

### 8. Toast notifications

```csharp
[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`.

```razor
<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:

```razor
<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](references/SETUP.md)
- [Layout and navigation](references/LAYOUT-AND-NAVIGATION.md)
- [Data grid](references/DATAGRID.md)
- [Theming](references/THEMING.md)

# FluentDataGrid

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

## Basic Usage

```razor
<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.

```razor
<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`.

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

### SelectColumn

Checkbox selection column.

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

Modes: `DataGridSelectMode.Single`, `DataGridSelectMode.Multiple`.

## Data Sources

Two mutually exclusive approaches:

### In-memory (IQueryable)

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

### Server-side / Custom (ItemsProvider)

```razor
<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

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

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

## Pagination

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

<FluentPaginator State="@pagination" />

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

## Virtualization

For large datasets, enable virtualization:

```razor
<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

| Parameter | Type | Description |
|---|---|---|
| `Items` | `IQueryable<TGridItem>?` | In-memory data source |
| `ItemsProvider` | `GridItemsProvider<TGridItem>?` | Async data provider |
| `Pagination` | `PaginationState?` | Pagination state |
| `Virtualize` | `bool` | Enable virtualization |
| `ItemSize` | `float` | Estimated row height (px) |
| `ItemKey` | `Func<TGridItem, object>?` | Stable key for `@key` |
| `ResizableColumns` | `bool` | Enable column resize |
| `HeaderCellAsButtonWithMenu` | `bool` | Sortable header UI |
| `GridTemplateColumns` | `string?` | CSS grid-template-columns |
| `Loading` | `bool` | Show loading indicator |
| `ShowHover` | `bool` | Highlight rows on hover |
| `OnRowClick` | `EventCallback<FluentDataGridRow<TGridItem>>` | Row click handler |
| `OnRowDoubleClick` | `EventCallback<FluentDataGridRow<TGridItem>>` | Row double-click handler |
| `OnRowFocus` | `EventCallback<FluentDataGridRow<TGridItem>>` | Row focus handler |

## Sorting

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

Or with a custom sort:

```razor
<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.

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

### FluentHeader / FluentFooter

Sticky header and footer sections within `FluentLayout`.

```razor
<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.

```razor
<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.

```razor
<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.

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

## Navigation Components

### FluentNavMenu

Collapsible navigation menu with keyboard support.

```razor
<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.

```razor
<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.

```razor
<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

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

### FluentTab / FluentTabs

```razor
<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

| Package | Purpose |
|---|---|
| `Microsoft.FluentUI.AspNetCore.Components` | Core component library (required) |
| `Microsoft.FluentUI.AspNetCore.Components.Icons` | Icon package (optional, recommended) |
| `Microsoft.FluentUI.AspNetCore.Components.Emojis` | Emoji package (optional) |
| `Microsoft.FluentUI.AspNetCore.Components.DataGrid.EntityFrameworkAdapter` | EF Core adapter for DataGrid (optional) |
| `Microsoft.FluentUI.AspNetCore.Components.DataGrid.ODataAdapter` | OData adapter for DataGrid (optional) |

## Program.cs Registration

```csharp
builder.Services.AddFluentUIComponents();
```

### Configuration Options (LibraryConfiguration)

| Property | Type | Default | Notes |
|---|---|---|---|
| `UseTooltipServiceProvider` | `bool` | `true` | Registers `ITooltipService`. If true, you MUST add `<FluentTooltipProvider>` to layout |
| `RequiredLabel` | `MarkupString` | Red `*` | Custom markup for required field indicators |
| `HideTooltipOnCursorLeave` | `bool` | `false` | Close tooltip when cursor leaves both anchor and tooltip |
| `ServiceLifetime` | `ServiceLifetime` | `Scoped` | Only `Scoped` or `Singleton`. `Transient` throws! |
| `ValidateClassNames` | `bool` | `true` | Validates CSS class names against `^-?[_a-zA-Z]+[_a-zA-Z0-9-]*$` |
| `CollocatedJavaScriptQueryString` | `Func<string, string>?` | `v={version}` | Cache-busting for JS files |

### ServiceLifetime by hosting model

| Hosting model | ServiceLifetime |
|---|---|
| Blazor Server | `Scoped` (default) |
| Blazor WebAssembly Standalone | `Singleton` |
| Blazor Web App (Interactive) | `Scoped` (default) |
| Blazor Hybrid (MAUI) | `Singleton` |

## MainLayout.razor Template

```razor
@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:

```razor
<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`:

```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()`:

| Service | Implementation | Purpose |
|---|---|---|
| `GlobalState` | `GlobalState` | Shared application state |
| `IToastService` | `ToastService` | Toast notifications (needs `FluentToastProvider`) |
| `IDialogService` | `DialogService` | Dialogs and panels (needs `FluentDialogProvider`) |
| `IMessageService` | `MessageService` | Message bars (needs `FluentMessageBarProvider`) |
| `IKeyCodeService` | `KeyCodeService` | Keyboard shortcuts (needs `FluentKeyCodeProvider`) |
| `IMenuService` | `MenuService` | Context menus |
| `ITooltipService` | `TooltipService` | Tooltips (needs `FluentTooltipProvider`, opt-in via `UseTooltipServiceProvider`) |

# Theming

## FluentDesignTheme (recommended)

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

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

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `Mode` | `DesignThemeModes` | `System` | `Light`, `Dark`, or `System` (follows OS) |
| `CustomColor` | `string?` | null | Hex accent color (e.g. `"#0078D4"`) |
| `OfficeColor` | `OfficeColor?` | null | Preset accent: `Teams`, `Word`, `Excel`, `PowerPoint`, `Outlook`, `OneNote` |
| `NeutralBaseColor` | `string?` | null | Neutral palette base hex color |
| `StorageName` | `string?` | null | Persist theme to localStorage under this key |
| `Direction` | `LocalizationDirection?` | null | `Ltr` or `Rtl` |
| `OnLuminanceChanged` | `EventCallback<LuminanceChangedEventArgs>` | | Fired when dark/light mode changes |
| `OnLoaded` | `EventCallback<LoadedEventArgs>` | | Fired when theme is loaded from storage |

### Two-way binding

```razor
<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:

```csharp
// 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.

```razor
<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.

```csharp
@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`.