Microsoft's Fluent UI Web Components is designed to help you build web apps using Web Components styled with the Fluent design language.
Fluent UI should be installed as a dependency of your app.
Yarn
yarn add @fluentui/web-components@betaNPM
npm i @fluentui/web-components@betapnpm
pnpm add @fluentui/web-components@betaA pre-bundled script that contains all APIs needed to use FAST Foundation 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@beta"></script>
</head>
<!-- ... -->
</html>The above CDN location points to the latest Beta 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.
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.
import { setTheme } from '@fluentui/web-components';
import { webLightTheme } from '@fluentui/tokens';
setTheme(webLightTheme);That's it. You can now use Fluent UI Web Components in your app.
Importing the defined component:
import '@fluentui/web-components/button.js';Defining the element yourself using named imports:
import { ButtonDefinition, FluentDesignSystem } from '@fluentui/web-components';
ButtonDefinition.define(FluentDesignSystem.registry);For convenience we have included a CEM (custom elements manifest) at the root of the project.
import CEM from '@fluentui/custom-elements.json' with { type: 'json' };To start the component development environment, run yarn start.
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:ssrTo check that the committed files match what the generators would produce (for example, before opening a PR), run:
yarn check:ssryarn 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 runyarn 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.tsor*.styles.tschange. 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.
Storybook will watch modules for changes and hot-reload the module when necessary. This is usually great but poses a problem when the module being hot-reloaded defines a custom element. A custom element name can only be defined by the CustomElementsRegistry once, so reloading a module that defines a custom element will attempt to re-register the custom element name, throwing an error because the name has already been defined. This error will manifest with the following message:
Failed to execute 'define' on 'CustomElementRegistry': the name "my-custom-element-name" has already been used with this registry
This is a known issue and will indicate that you need to refresh the page. We're working on surfacing a more instructive error message for this case.
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.