Using Fluent UI in SharePoint Framework

Fluent UI (formerly Office UI Fabric) is the official front-end framework for building experiences in Microsoft 365 and SharePoint. SharePoint provides seamless integration with Fluent UI that enables Microsoft to deliver a robust and consistent design language across various SharePoint experiences such as modern team sites, modern pages, and modern lists. Additionally, Fluent UI is available for developers in the SharePoint Framework when building custom SharePoint solutions.

Microsoft uses Fluent UI in SharePoint. Microsoft regularly pushes updates to SharePoint Online that could also update the Fluent UI versions as well. These updates could potentially conflict with third-party customer solutions built with previous versions of Fluent UI (or the legacy Office UI Fabric packages), which could cause exceptions in those customizations. The primary reason for these types of breaks is the use of Global CSS styles in both Fabric Core and Fluent UI React libraries. Such conflicts need to be avoided at all costs.

The challenge with Global CSS styles is explained in the following presentation within the context of React and JavaScript: React CSS in JS.

To achieve reliability, one of the main problems we need to solve is that of Global CSS styles. Use CSS Modules (.module.scss files, which SPFx scaffolds by default) or Fluent UI styling APIs (mergeStyles, makeStyles) instead of global Sass mixins. If you're maintaining a legacy project that still relies on Fabric Core Sass declarations, import them through the scoped @microsoft/sp-office-ui-fabric-core package rather than referencing global class names directly in HTML markup.

Goals

The goal of the SharePoint Framework is to allow both Microsoft and customers to build rich, beautiful, and consistent user experiences on top of SharePoint.

In accordance with these goals, following are the key design principles:

• Customers should be able to smoothly and reliably consume Fabric Core and Fluent UI React in their solutions.
• Microsoft will roll out updated experiences that consume updated versions of Fluent UI in SharePoint without conflicting with customer's solutions.
• Customers can customize and override the default styles, designs, and components to tailor the solution's needs.

There are two parts of Fluent UI that are available for use by developers:

• Fluent UI Core Styles. A set of core styles, typography, a responsive grid, animations, icons, and other fundamental building blocks of the overall design language (formerly Office UI Fabric Core).

• Fluent UI React. A set of React components built on top of the Fluent UI design language for use in React-based projects (formerly Office UI Fabric React).

Fabric Core styles package

The SharePoint Framework Fabric Core npm package (@microsoft/sp-office-ui-fabric-core) contains a subset of supported Fabric Core styles that can be safely consumed within a SharePoint Framework component.

The following core styles are supported in the package:

• Typography
• Layouts
• Colors
• Themes
• Localization

The following aren't yet supported in the package:

• Animations
• Icons

Starting with the SharePoint Framework Yeoman generator version 1.3.4, the default project (web parts and extensions) templates come setup with the new @microsoft/sp-office-ui-fabric-core package and consume core styles from the package instead of using global CSS styles.

Update existing projects

To use the Fabric Core package in your existing project, install the package as a dependency:

npm install @microsoft/sp-office-ui-fabric-core --save

After it's installed, you can then import the Fabric Core Sass declarations in your Sass definition file and use the mixins and variables as described in the following section.

Use Fabric Core styles

To use the Fabric Core styles, you need to import the SPFabricCore declarations into your Sass file.

@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

Now you can use the core styles as mixins and variables.

.row {
  @include ms-Grid-row;
  @include ms-fontColor-white;
  background-color: $ms-color-themeDark;
  padding: 20px;
}

Fluent UI React (formerly Office UI Fabric React)

We recommend that you use the version of the Fluent UI React package included in your SharePoint Framework project by the Yeoman generator.

• SPFx v1.18 and later: Projects use the @fluentui/react (v8) package.
• SPFx v1.17 and earlier: Projects use the legacy office-ui-fabric-react (v7 or earlier) package.

After the Fluent UI React package is installed, you can import the required components from the package.

For SPFx v1.18+ projects using @fluentui/react:

import { DefaultButton } from '@fluentui/react/lib/Button';

// use it in your component
render() {
  ...
  <div>
    <DefaultButton>click me</DefaultButton>
  </div>
  ...
}

For legacy projects using office-ui-fabric-react:

import { DefaultButton } from 'office-ui-fabric-react/lib/Button';

// use it in your component
render() {
  ...
  <div>
    <DefaultButton>click me</DefaultButton>
  </div>
  ...
}

The Fluent UI React package includes the supported core styles used in the components. We recommend that you import the core styles from the Fluent UI React package instead of from the @microsoft/sp-office-ui-fabric-core package to ensure that the right styles are used in your component.

Because the @microsoft/sp-office-ui-fabric-core package is already installed in your solution by the Yeoman generator, we recommend that you uninstall that package if you decide to use Fluent UI React components to reduce your component bundle size.

npm uninstall @microsoft/sp-office-ui-fabric-core --save

You can then import the core styles from the Sass declarations available in the Fluent UI React package.

For @fluentui/react:

@import '~@fluentui/react/dist/sass/_References.scss';

For legacy office-ui-fabric-react:

@import '~office-ui-fabric-react/dist/sass/_References.scss';

Understanding this approach and its shortcomings

Fluent UI components in your solution are locked to the specific version that you installed. You need to update the Fluent UI React package to get any new components if they're available in a newer package version. Because the components are included in the component bundle, it may increase the size of your component bundle. However, this approach is the only approach that is officially supported when Fluent UI React is being used in SharePoint Framework solutions.

The CSS challenge with Fluent UI

The following concepts and references provide insights on the challenge with using Fluent UI (formerly Office UI Fabric) in the context of client-side web parts.

Global CSS styles

How to avoid Global CSS styles at all costs is a significant problem. Today, both Fabric Core and Fabric React have global styles. A lack of any native solutions from the browser to manage the style scoping makes this a difficult problem.

• Scope CSS is in early stages of discussion.
• iframes aren't a good option to isolate styles.
• Web Components is another standard that talks about scoped styles but is still in the discussion stage.
• The React: CSS in JS discussion explains the problem well.

There's plenty of other documentation on the web about the solutions to the global namespace menace.

CSS specificity

How CSS specificity applies to web UI. Higher specificity styles override lower specificity styles, but the key thing to understand is how the specificity rules apply. In general, the precedence order from highest to lowest is as follows:

• The style attribute (for example, style="background:red;")
• ID selectors (#myDiv { })
• Class selectors (.myCssClass{}), attribute selectors ([type="radio"]), and pseudo-classes (:hover)
• Type selectors (h1)

Loading order. If two classes are applied on an element and have the same specificity, the class that is loaded later takes precedence. As shown in the following code, the button appears red. If the order of the style tags is changed, the button appears green. This is an important concept, and if not used correctly, the user experience can become load order-dependent (that is, inconsistent).

<style>
  .greenButton { color: green; }
</style>
<style>
  .redButton { color: red; }
</style>
<body>
  <button class="greenButton redButton"></button>
</body>

Other approaches considered and discarded

The Following are extra insights on the other approaches that were considered but discarded because they didn't achieve the key objectives to enable third-party developers to safely use the Office UI Fabric styles.

Office UI Fabric Core

The web part developer wouldn't be required to do anything explicitly to get the scoping to work. We planned to solve this problem through CSS specificity and descendant selectors. The Fabric Core team would ship multiple copies of Fabric Core css (for example, fabric-6.css, fabric-6-scoped.css, fabric-6.0.0.css, fabric-6.0.0-scoped.css).

All the styles in the scoped CSS files would be inside a descendant selector, for example .ms-Fabric--v6-0-0 .ms-Icon--List. At compile time, the tooling would collect the version of the Office UI Fabric Core that the web part was built with. This version could be the one that comes with SharePoint Framework. Alternatively, web part developers could specify an explicit dependency on a specific version of Office UI Fabric Core in their package.json file.

The web part div would be assigned this scope, that is <div data-sp-webpart class="ms-Fabric--v6-0-0">. The Framework would load the specific major version of the Fabric Core-scoped CSS file. If the web part was built with version 6.0.0 of the Fabric Core CSS, the Framework would download fabric-6-scoped.css when the web part was loaded.

The rest of the page would contain unscoped Office UI Fabric Core styles. This way, as per CSS specificity rules, the scoped CSS would take precedence within the web part div. The web part and its contents would align to the specific version of the Office UI Fabric Core that the developer had chosen.

Overriding Fabric Core styles wouldn't be supported.

// Sample of how the scoping would work.
import { SPComponentLoader } from '@microsoft/sp-loader';

export default class MyWebPart {
    constructor() {
        super();

        SPComponentLoader.loadCss('https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/6.0.0/css/fabric-6.0.0.scoped.css');
    }
}

protected render(): void {
  <div className="ms-Fabric--v6-0-0">
    { // Rest of the web part UI }
  </div>
}

Shortcomings of this strategy

After analyzing this strategy for a while, it was decided that the descendant selector approach has two serious shortcomings that would make it impossible to build a web part that would never break.

Lack of reliable nesting support

This approach only works if the Microsoft user experience (that is, page and first-party web parts) uses an unscoped version of the Office UI Fabric Core such as ms-Icon--List, while the third-party web parts only use scoped Office UI Fabric Core CSS as explained earlier.

The reason being that the specificity of the scoped CSS applied on the web part overrides the unscoped CSS on the page. Keep in mind, as explained earlier, that if CSS specificity of the two classes is the same, their loading order plays a role in how the CSS classes are applied. The class that loads later takes precedence. Hence, the higher specificity of the scoped CSS is important in getting a consistent experience.

Furthermore, multiple extensions, one contained in the other, can't use different Fabric Core versions. In the following example, only ms-Fabric--v6-0-0 would get applied:

<div className="ms-Fabric--v6-0-0">
  { // Rest of the web part UI }
    { // inside of this SPExtension trying to use different Fabric core version does not work }
    <div className="ms-Fabric--v8-0-0">
    </div>
</div>

Here's a more simplistic sample demonstrating the challenge:

<html>
<head>
  <title>CSS specifity test</title>
  <style>
  .myButton {
      background-color: brown;
      color: brown;
      height: 20px;
      width: 40px;
  }
  </style>
  <style>
  .scope2 .myButton {
      background-color: green;
      color: green;
  }
  </style>
  <style>
  .scope3 .myButton {
      background-color: yellow;
      color: yellow;
  }
  </style>
  <style>
  .scope1 .myButton {
      background-color: red;
      color: red;
  }
  </style>
</head>
<body>
  <div>
    <span>These tests demonstrate descendant selectors, nesting and load order problems.</span>

    <div>
      <br/>
      <span>This test depicts that a descendant selector with the same specificity does not allow nesting.
      All buttons below do not take the innermost scope (i.e. they should be different colors), but they are all red.
      Further, if you change the ordering of the style tags, the colors will change. (i.e. the UI is load order dependant.)</span>
      <div class='scope1'>
        <button class='myButton'</button>
        <div class='scope2'>
          <button class='myButton'></button>
          <div class='scope3'>
            <button class='myButton'></button>
          </div>
        </div>
      </div>
    </div>
  </div>
</body>
</html>

Leakage from unscoped classes

There's another problem with descendant selectors. Note in the previous example that the height and the width styles from the unscoped myButton class are applied to all the buttons. This implies that a change in that style could inadvertently break HTML by using scoped markup.

Say, for example, for some reason at the app level we decide to make height 0 px on the myButton class. That results in all third-party web parts that use the myButton class to have a height of 0 px (that is, a serious regression in the user experience).

Safely use legacy Office UI Fabric Styles (after SPFx v1.8.2)

Ensure that the web part manifest demands legacy Fabric core styles be loaded onto the page. This is done by specifying loadLegacyFabricCss: true in the solution manifest.

Prior to the release of SPFx v1.8.2, a host page bug was present where legacy Fabric core styles were loaded unscoped. Therefore, if another solution demanded the styles, then all other solutions on the page were able to use them. This led to solutions working "by chance" when not rendered in isolation.

To address this bug, the styles were scoped to .ms-SPLegacyFabricBlock class and applied to SPFx solutions that demand the Fabric core stylesheet be loaded. To provide a migration path for solutions reliant on the side-effect above, the .ms-SPLegacyFabricBlock class is applied to all <div>'s exposed to third-party solutions. During that time, modify the solution(s) impacted to declare the dependency on legacy Fabric core styles.

In the event of a solution that's running in DOM elements that aren't provided by the SPFx (which is unsupported), you'll need to apply the .ms-SPLegacyFabricBlock class yourself.

Usage of Fluent UI icons in SPFx components

There are changes on how to use Fluent UI (formerly Office UI Fabric) icons in the rendering of the SharePoint Framework solutions starting from the SharePoint Framework v1.8.2.

Legacy way of using icons (before SPFx 1.8.2)

<i className={css('ms-Icon', 'ms-Icon--RecurringEvent')}></i>

Updated way to use icons (after SPFx 1.8.2)

Solutions built with no JavaScript framework option.

For SPFx v1.18+ using @fluentui/react:

import { getIconClassName } from '@fluentui/react/lib/Styling';

return `<i class="${getIconClassName('Mail')}" />`;

For legacy projects using @uifabric/styling:

import { getIconClassName } from '@uifabric/styling';

return `<i class="${getIconClassName('Mail')}" />`;

Solutions built with React option or by using React in general.

For SPFx v1.18+ using @fluentui/react:

import { Icon } from '@fluentui/react/lib/Icon';

<Icon iconName='Mail' />

For legacy projects using office-ui-fabric-react:

import { Icon } from 'office-ui-fabric-react/lib/Icon';

<Icon iconName='Mail' />

See also

• Fluent UI
• Overview of the SharePoint Framework