Use Fluent UI Web Components with Blazor
The Microsoft.Fast.Components.FluentUI package provides a set of Blazor components which you can use to build applications that have
the look and feel or modern Microsoft applications. Some of the componets are wrappers around Microsoft's official FluentUI Web Components. Others are components
that leverage the Fluent UI design system or make it easier to work with Fluent UI. To get up and running with the library, see the 'Getting Started' section below.
Upgrading from an earlier version
If you are upgrading from an earlier version of the library, please see the what's new for information on (breaking) changes.
Getting Started
To get started using the Fluent UI Blazor components for Blazor, you will first need to install the official Nuget package for Fluent UI in the project you would like to use the library and components. You can use the following command:
dotnet add package Microsoft.Fast.Components.FluentUI
Script
The hart of this library is formed by the Fluent UI Web Components and the accompanying web-components.min.js file. From version 2.3 onwards, the
script is included in the library itself and no longer needs to be added to your index.html or _Layout.cshtml. In fact, doing this might lead to
unpredictable results.
Important
If you are upgrading from an earlier version please remove the script from your index.html or _Layout.cshtml file.
The script is added to the application automatically. This way we can safeguard that the you are always using the best matching script version.
Styles
In order for this library to work as expected, you will need to add the composed scoped CSS file for the components. This can be done by
adding the following line to the <head> section of your index.html or _Layout.cshtml file in the project you installed the package:
<link href="{PROJECT_NAME}.styles.css" rel="stylesheet" />
📓 Note
If you prefer to use another CDN, that is entirely possible. Just make sure it is offering the Fluent UI package and you are getting the right
web-components.min.jsfile)
It is possible that the line is already in place (but commented out).
Reboot
Reboot is a collection of element-specific CSS changes in a single file to help kick-start building a site with the Fluent UI Blazor components for Blazor. It provides an elegant, consistent, and simple baseline to build upon.
If you want to use Reboot, you'll need to add to your index.html or _Layout.cshtml file a line that includes the stylesheet (.css file). This can be done by adding the following line to the <head> section:
<link href="_content/Microsoft.Fast.Components.FluentUI/css/reboot.css" rel="stylesheet" />
It is entirely possible to build a site without using Reboot. If you choose not to use it, please do add the variables.css file (which is otherwise imported through the reboot.css file)
to your index.html or _Layout.cshtml file in the <head> section like this:
<link href="_content/Microsoft.Fast.Components.FluentUI/css/variables.css" rel="stylesheet" />
The file contains a number of CSS variables that are required to be defined for the components to work correctly.
Project file
if you want to use icons and/or emoji, starting with version 2.1 you need add a <PropertyGroup> to your project file. With this you can specify which icons and emoji are made available for usage and publication. Please refer to the project setup document for more information.
Code
Please refer to the code setup document to learn what needs to be included in your Program.cs file
so that all necessary services are available and setup in the correct way.
Getting started by using project templates
To make it easier to start a project that uses the Fluent UI Web Components for Blazor out of the box, we have created the Microsoft.Fast.Templates.FluentUI template package.
The package contains templates for creating Blazor Server and/or Blazor WebAssembly apps that mimic the regular Blazor templates with the Fluent UI components already set up (and all the Bootstrap styling removed). All components have been replaced with Fluent UI counterparts (and a few extra have been added). Please see the documentation page for more information.
If you want to use icons and/or emoji with applications based on the templates, you still need to make the changes to the project file
and Program.cs as described in the project setup and code setup documents.
Using the FluentUI Web Components
With the package installed and the script configured, you can begin using the Fluent UI Blazor components in the same way as any other Blazor component. Just be sure to add the following using statement to your views:
@using Microsoft.Fast.Components.FluentUI
Here's a small example of a FluentCard with a FluentButton that uses the Fluent "Accent" appearance:
@using Microsoft.Fast.Components.FluentUI
<FluentCard>
<h2>Hello World!</h2>
<FluentButton Appearance="@Appearance.Accent">Click Me</FluentButton>
</FluentCard>
Tip
You can add @using Microsoft.Fast.Components.FluentUI to the namespace collection in _Imports.razor, so you don't have to add it to every razor page
that uses one of the components.
If you are using the .NET CLI, you can run your project with the following command from the project folder:
dotnet watch run
Congratulations! You're now set up to use the Fluent UI Web Components with Blazor!
Configuring the Design System
The Fluent UI Blazor components are built on FAST's Adaptive UI technology, which enables design customization and personalization, while automatically
maintaining accessibility. This is accomplished through setting various "Design Tokens". The library exposes all of the (over 160) Design Tokens, which you can use both from code as in a declarative way in your .razor pages. The three different ways of working with design tokens are described in the design tokens page.
Blazor Hybrid
Starting with the 2.0 release, you can also use this library in your Blazor Hybrid projects. Setup is almost the same as described in the "Getting started" section above, but to get everything to work you'll need to take two extra steps:
- You need to add a MAUI specific IStaticAssetService implementation.
Due to some issues, this file can't be part of the library (yet) so this needs to be added manually to your MAUI Blazor project.
Create a new class in you project calledFileBasedStaticAssetService.csReplace it's contents with the following:
using System.Net;
using Microsoft.Fast.Components.FluentUI.Infrastructure;
namespace Microsoft.Fast.Components.FluentUI;
public class FileBasedStaticAssetService : IStaticAssetService
{
public async Task<string> GetAsync(string assetUrl, bool useCache = false)
{
string result = null;
HttpRequestMessage message = CreateMessage(assetUrl);
if (string.IsNullOrEmpty(result))
{
result = await ReadData(assetUrl);
}
return result;
}
private static HttpRequestMessage CreateMessage(string url) => new(HttpMethod.Get, url);
private static async Task<string> ReadData(string file)
{
using var stream = await FileSystem.OpenAppPackageFileAsync($"wwwroot/{file}");
using var reader = new StreamReader(stream);
return await reader.ReadToEndAsync();
}
}
- You need to make some changes in your
MauiProgram.csfile
Make sure the following is added before thereturn builder.Build()line:
builder.Services.AddFluentUIComponents(options =>
{
options.HostingModel = BlazorHostingModel.Hybrid;
});
builder.Services.AddScoped<IStaticAssetService, FileBasedStaticAssetService>();
Use the DataGrid component with EF Core
If you want to use the <FluentDataGrid> with data provided through EF Core, you need to install
an additional package so the grid knows how to resolve queries asynchronously for efficiency. .
Installation
Install the package by running the command:
dotnet add package Microsoft.Fast.Components.FluentUI.DataGrid.EntityFrameworkAdapter
Usage
In your Program.cs file you need to add the following after the builder.Services.AddFluentUIComponents(...); lines:
builder.Services.AddDataGridEntityFrameworkAdapter();
To report issues or provide feedback on Microsoft.Fast.Components.FluentUI, please visit the microsoft/fluentui-blazor repository.