Themes

The FluentDesignTheme component lets you quickly manage the primary/main color and mode (dark/light) of your entire application.
If you'd like to customize all of the design details of your application, or just a very specific part, please use the DesignTokens

Quick guide

1. First, choose a name to save the theme mode (dark/bright) and color, in the browser's local storage. for example: theme.

2. Next, add this line to your App.razor file (or your Layout page), to automatically apply the theme to all your pages.

<FluentDesignTheme StorageName="theme" />

3. (optional) To ensure that your application is displayed correctly, we recommend you add these lines of code to your app.css file. If you were using the Reboot style, as shown on the Setup page, these styles are already included.

body {
    margin: 0;
    padding: 0;
    height: 100vh;
    font-family: var(--body-font);
    font-size:   var(--type-ramp-base-font-size);
    line-height: var(--type-ramp-base-line-height);
    font-weight: var(--font-weight);
    color:       var(--neutral-foreground-rest);
    background:  var(--neutral-fill-layer-rest);
}

4. (optional) To avoid a "flash" effect when the page loads (mainly in dark mode), as described below, we recommend you add these lines of code to the index.html or App.razor file (or _layout.cshtml file if you upgraded you project from an earlier .NET version).

<!-- Set the default theme -->
<script src="_content/Microsoft.FluentUI.AspNetCore.Components/js/loading-theme.js" type="text/javascript"></script>
<loading-theme storage-name="theme"></loading-theme>

5. Finally, you can add a button or page that allows the user to choose their theme. To do this, you need to use a FluentDesignTheme component on which you can bind the Mode and the OfficeColor properties, and to set a StorageName to save all this in the LocalStorage.

<FluentDesignTheme @bind-Mode="@Mode" @bind-OfficeColor="@OfficeColor" StorageName="theme" />

FluentDesignTheme

FluentDesignTheme is a Blazor component. It comes with an additional web component (fluent-design-theme) that can be used in HTML before Blazor has started and components are rendered. This avoids a "flash" of dark or white at page startup. Particularly so when using a WebAssembly project, which in general requires more time to download the assemblies needed to run the application.

Example in HTML

<fluent-design-theme mode="dark" primary-color="word" />
<fluent-design-theme mode="light" primary-color="#ff0000" />

<FluentDesignTheme Mode="DesignThemeModes.Dark" OfficeColor="OfficeColor.Word" />
<FluentDesignTheme Mode="DesignThemeModes.Light" CustomColor="#ff0000" />

Mode

For the Blazor FluentDesignTheme component, you can define the mode of your application.

• System: respects the browser's appearance.
• Dark: forces the appearance in Dark theme.
• Light: forces the appearance in Light theme.

OnLuminanceChanged

When the theme is updated, the OnLuminanceChanged event is triggered.

LocalStorage

The FluentDesignTheme component contains an optional StorageName attribute to define the name of the local storage to automatically save and retrieve the selected Mode and PrimaryColor.

Don't set/use this property, if you want your application users to be able set your application's theme manually. On the other hand, do set a value (e.g. theme) to automatically let the component save the theme choice and retrieve it the next time the application is visited.

Theme settings are saved in the browser's LocalStorage section.

"theme" = {"mode": "light", "primaryColor": "word"}

How to remove the "bright flash" on loading

Depending on the size of the file to be downloaded or the user's bandwidth, there may be a "bright flash" effect when the page is loaded. (a white page displayed some milliseconds before the Dark theme is present). This is due to the fact that Blazor's complete engine cannot display a Dark page until the code (JS and WebAssembly) has been downloaded and executed.

To avoid this, we propose a component separate from the main library, whose only purpose is to detect the dark/light mode to be displayed, until the main components are loaded.

<script src="_content/Microsoft.FluentUI.AspNetCore.Components/js/loading-theme.js" type="text/javascript"></script>
<loading-theme storage-name="theme"></loading-theme>

In this example, the storage-name="theme" searches for a optional theme saved in the browser's LocalStorage.
You can also "force" the Dark theme using a syntax like <loading-theme mode="dark" />

Technically, this loading-theme component adds a hidden-body class (visibility: hidden; background-color: #272727;) to the body tag during the loading time of all FluentUI components. Once they are integrated into the browser, this class is removed and the content is displayed.

Example

Documentation