@fluentui/web-components

v3.0.2

Published

3 days ago

A library of Fluent Web Components

0High
0Medium
0Low

uifabricteam

uifrnbot

microsoft1es

microsoft-oss-releases

Fluent UI Web Components

Microsoft's Fluent UI Web Components is designed to help you build web apps using Web Components styled with the Fluent design language.

Installation

Install

Fluent UI should be installed as a dependency of your app.

Yarn

yarn add @fluentui/web-components

NPM

npm i @fluentui/web-components

pnpm

pnpm add @fluentui/web-components

From CDN

A pre-bundled script that contains all APIs needed to use Fluent UI Web Components is available on CDN. You can use this script by adding type="module" to the script element and then importing from the CDN.

<!DOCTYPE html>
<html lang="en">
  <head>
    <script type="module" src="https://unpkg.com/@fluentui/web-components"></script>
  </head>
  <!-- ... -->
</html>

The above CDN location points to the latest release of @fluentui/web-components. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with.

For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.

Setup

Required Theming

Fluent UI Web Components are styled using tokens in the form of CSS variables. You can use the setTheme utility to provide a theme for your website or application.

Available themes:

webLightTheme
webDarkTheme

Theme implementation:

import { setTheme } from '@fluentui/web-components';
import { webLightTheme } from '@fluentui/tokens';

setTheme(webLightTheme);

Usage

Each component can be directly imported. The side effect only module will call define and cause it to be set up.

Defining Components

Importing a defined component:

import '@fluentui/web-components/button.js';

Importing all defined components:

import '@fluentui/web-components/web-components.js';

Defining Declarative Components

Each component provides a declarative f-template.

Include an f-template on your page, you can find it at '@fluentui/web-components/button/template.html'.

Importing a defined component:

import '@fluentui/web-components/button/define-async.js';

Hydrating Declarative Components

For more information about including hydratable syntax, we recommend using an integration with WebUI Framework project.

More information about FAST hydration.

Custom Elements Manifest

We ship a CEM (custom elements manifest) from the root of the bundle.

import CEM from '@fluentui/web-components/custom-elements.json' with { type: 'json' };

Contributing

To start the component development environment, run yarn start.

SSR templates and stylesheets

Each component ships a declarative-shadow-DOM template (*.template.html) and an extracted stylesheet (*.styles.css) next to its *.template.ts and *.styles.ts sources. These files are generated from the TypeScript sources and committed to the repo so the DSD output is visible without running a build.

After editing a *.template.ts or *.styles.ts, regenerate the matching HTML and CSS with:

yarn generate:ssr

To check that the committed files match what the generators would produce (for example, before opening a PR), run:

yarn check:ssr

yarn compile does not regenerate these files; it copies them from src/ into dist/esm/ alongside the compiled JS.

Use the yarn check:ssr summary to avoid clobbering intentional SSR-only edits:

stale: the committed source and generated file are unchanged, but regeneration disagrees with disk. Rebase if needed, then run yarn generate:ssr, review the generated diff, and commit it with the related source or generator change.
hand-edited: the generated HTML/CSS changed without a matching *.template.ts or *.styles.ts change. Do not overwrite it blindly; either move the intended delta into the TypeScript source or generator before regenerating, or reapply and call out the intentional SSR-only edit in the PR.
conflicts: both the TypeScript source and generated file changed, and regeneration still disagrees with disk. Treat this like a merge conflict: inspect the current generated-file diff, regenerate, then preserve only the intentional SSR delta before committing.

Keep generated-file updates scoped to the component you changed. If yarn check:ssr reports unrelated stale files, leave them out of your PR and coordinate a dedicated cleanup.

Testing

On CI, a static test harness build is first generated by running Vite in build mode. The Playwright tests are then run against the generated harness. To run Playwright tests in this mode, use the command yarn nx run web-components:e2e.

To run Playwright tests locally in UI mode, use the command yarn nx run web-components:e2e:local. This will start a local development server with Vite and open the Playwright test runner UI.