Fluent UI Web Components

Fluent UI Web Components — Knowledge Base

1. Overview

Fluent UI Web Components provide Microsoft's Fluent 2 design language as framework-agnostic custom elements built on the FAST element platform. They render in every environment that supports the Web Components standard — vanilla HTML/JS, Angular, Vue, Svelte, Blazor, PHP templates, or any micro-frontend shell.

When to use Web Components vs React v9

Key characteristics

• Shadow DOM encapsulation — styles don't leak in or out
• Custom element registration — <fluent-button>, <fluent-card>, etc.
• Design token CSS custom properties — theme via --fill-color, --accent-base-color, etc.
• FAST foundation — element lifecycle, template binding, observable properties
• Tree-shakeable — import only the components you need

Package identity

Official documentation:

• https://learn.microsoft.com/en-us/fluent-ui/web-components/
• https://learn.microsoft.com/en-us/fluent-ui/web-components/components/overview
• https://www.npmjs.com/package/@fluentui/web-components

2. Package Setup

npm / yarn / pnpm

# npm
npm install @fluentui/web-components

# yarn
yarn add @fluentui/web-components

# pnpm
pnpm add @fluentui/web-components

Register all components (quick start)

import {
  provideFluentDesignSystem,
  allComponents,
} from "@fluentui/web-components";

provideFluentDesignSystem().register(allComponents);

Register individual components (tree-shaking)

import {
  provideFluentDesignSystem,
  fluentButton,
  fluentCard,
  fluentTextField,
} from "@fluentui/web-components";

provideFluentDesignSystem().register(
  fluentButton(),
  fluentCard(),
  fluentTextField()
);

CDN usage (no bundler)

<script type="module" src="https://unpkg.com/@fluentui/web-components"></script>

Or for a specific version:

<script
  type="module"
  src="https://unpkg.com/@fluentui/web-components@3.0.0/dist/web-components.min.js"
></script>

TypeScript configuration

Add Web Component type declarations for HTML element inference:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "target": "ES2021",
    "module": "ES2022",
    "lib": ["ES2021", "DOM", "DOM.Iterable"]
  }
}

3. Design Token Integration

Fluent Web Components use CSS custom properties (design tokens) for all visual values. Tokens are set on a <fluent-design-system-provider> or on any ancestor element.

How tokens flow

1. Global defaults — The component library ships sensible defaults.
2. Design system provider — Wrap the app or a section to override tokens.
3. Inline overrides — Any element's style attribute can set --token-name.

Design system provider

<fluent-design-system-provider
  fill-color="#ffffff"
  accent-base-color="#0078d4"
  neutral-base-color="#808080"
  base-layer-luminance="1"
>
  <!-- All children inherit these tokens -->
  <fluent-button appearance="accent">Themed Button</fluent-button>
</fluent-design-system-provider>

Common CSS custom property tokens

Dark mode

Toggle dark mode by changing base-layer-luminance:

<!-- Light mode -->
<fluent-design-system-provider base-layer-luminance="1">
  ...
</fluent-design-system-provider>

<!-- Dark mode -->
<fluent-design-system-provider base-layer-luminance="0.15">
  ...
</fluent-design-system-provider>

Nested theming

Providers can nest to create themed regions:

<fluent-design-system-provider base-layer-luminance="1" accent-base-color="#0078d4">
  <fluent-card>
    <p>Light region with blue accent</p>
  </fluent-card>

  <fluent-design-system-provider base-layer-luminance="0.15" accent-base-color="#9b59b6">
    <fluent-card>
      <p>Dark region with purple accent</p>
    </fluent-card>
  </fluent-design-system-provider>
</fluent-design-system-provider>

Programmatic token access

import {
  fillColor,
  accentBaseColor,
  baseLayerLuminance,
} from "@fluentui/web-components";

const provider = document.querySelector("fluent-design-system-provider");
fillColor.setValueFor(provider, "#f5f5f5");
accentBaseColor.setValueFor(provider, "#0078d4");
baseLayerLuminance.setValueFor(provider, 1);

4. Component Catalog

All components are registered as custom elements with a fluent- prefix. Below is the full catalog. For exhaustive attribute/event/slot/CSS-part details, load the reference:

${CLAUDE_PLUGIN_ROOT}/skills/fluent-web-components/references/web-components-catalog.md

Interactive controls

Layout & containers

Data display

Feedback & progress

Form structure

Quick examples

<!-- Accent button -->
<fluent-button appearance="accent">Save Changes</fluent-button>

<!-- Text field with label -->
<fluent-field label-position="above">
  <label slot="label">Email address</label>
  <fluent-text-field slot="input" type="email" placeholder="user@example.com">
  </fluent-text-field>
</fluent-field>

<!-- Card container -->
<fluent-card>
  <h3>Project Status</h3>
  <fluent-badge appearance="filled" color="success">Active</fluent-badge>
  <p>All systems operational.</p>
</fluent-card>

<!-- Accordion -->
<fluent-accordion expand-mode="single">
  <fluent-accordion-item expanded>
    <span slot="heading">Section One</span>
    <p>Content for section one.</p>
  </fluent-accordion-item>
  <fluent-accordion-item>
    <span slot="heading">Section Two</span>
    <p>Content for section two.</p>
  </fluent-accordion-item>
</fluent-accordion>

5. DataGrid Web Component

The <fluent-data-grid> is the most complex Web Component and deserves detailed coverage.

Reference: https://learn.microsoft.com/en-us/fluent-ui/web-components/components/data-grid

Basic usage

<fluent-data-grid id="myGrid" generate-header="sticky" grid-template-columns="1fr 1fr 1fr">
</fluent-data-grid>

<script>
  const grid = document.getElementById("myGrid");
  grid.rowsData = [
    { name: "Alice Johnson", role: "Engineer", status: "Active" },
    { name: "Bob Smith", role: "Designer", status: "Away" },
    { name: "Carol Lee", role: "PM", status: "Active" },
  ];
</script>

Column definitions

For explicit column control, define columnDefinitions:

grid.columnDefinitions = [
  { columnDataKey: "name", title: "Name" },
  { columnDataKey: "role", title: "Role" },
  {
    columnDataKey: "status",
    title: "Status",
    cellTemplate: (cell, row) => {
      const badge = document.createElement("fluent-badge");
      badge.textContent = row.status;
      badge.setAttribute("color", row.status === "Active" ? "success" : "warning");
      return badge;
    },
  },
];

Sorting

Sorting is implemented via column header click handlers:

grid.columnDefinitions = [
  {
    columnDataKey: "name",
    title: "Name",
    isRowHeader: true,
    headerCellTemplate: /* custom sort header template */,
  },
  { columnDataKey: "role", title: "Role" },
];

// Sort handler
grid.addEventListener("click", (e) => {
  const header = e.target.closest("fluent-data-grid-cell[cell-type='columnheader']");
  if (!header) return;

  const columnKey = header.columnDefinition?.columnDataKey;
  if (!columnKey) return;

  const sorted = [...grid.rowsData].sort((a, b) =>
    String(a[columnKey]).localeCompare(String(b[columnKey]))
  );
  grid.rowsData = sorted;
});

Row selection

grid.addEventListener("row-focused", (e) => {
  const row = e.detail;
  console.log("Selected row data:", row);
});

Column resizing

Set grid-template-columns to enable user-controlled column widths:

<fluent-data-grid
  grid-template-columns="minmax(150px, 1fr) minmax(100px, 1fr) 120px"
  generate-header="sticky"
>
</fluent-data-grid>

Virtualization with large datasets

For large datasets, batch-render rows or use IntersectionObserver for virtual scrolling:

const PAGE_SIZE = 50;
let currentPage = 0;

function loadPage(page) {
  const start = page * PAGE_SIZE;
  grid.rowsData = allData.slice(start, start + PAGE_SIZE);
}

loadPage(0);

6. Framework Integration

6.1 Vanilla JS / HTML

The simplest approach — no framework tooling needed.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Fluent Web Components — Vanilla</title>
  <script type="module">
    import {
      provideFluentDesignSystem,
      fluentButton,
      fluentCard,
      fluentTextField,
    } from "https://unpkg.com/@fluentui/web-components";

    provideFluentDesignSystem().register(
      fluentButton(),
      fluentCard(),
      fluentTextField()
    );
  </script>
</head>
<body>
  <fluent-design-system-provider base-layer-luminance="1" accent-base-color="#0078d4">
    <fluent-card>
      <h2>Contact Form</h2>
      <fluent-text-field placeholder="Your name"></fluent-text-field>
      <fluent-button appearance="accent" id="submitBtn">Submit</fluent-button>
    </fluent-card>
  </fluent-design-system-provider>

  <script>
    document.getElementById("submitBtn").addEventListener("click", () => {
      alert("Form submitted!");
    });
  </script>
</body>
</html>

6.2 Angular

Angular fully supports custom elements via CUSTOM_ELEMENTS_SCHEMA.

Step 1 — Install:

npm install @fluentui/web-components

Step 2 — Register components in main.ts:

import {
  provideFluentDesignSystem,
  fluentButton,
  fluentCard,
  fluentTextField,
} from "@fluentui/web-components";

provideFluentDesignSystem().register(
  fluentButton(),
  fluentCard(),
  fluentTextField()
);

Step 3 — Enable custom elements in module:

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  // ...
})
export class AppModule {}

Step 4 — Use in templates with property binding:

<fluent-text-field
  [placeholder]="'Enter your name'"
  (change)="onNameChange($event)"
></fluent-text-field>

<fluent-button
  [appearance]="'accent'"
  [disabled]="isSubmitting"
  (click)="onSubmit()"
>
  Submit
</fluent-button>

Important: Use property binding [attr] for properties and (event) for events. Angular's standard attribute binding works for string attributes.

6.3 Vue

Vue 3 recognizes custom elements automatically when configured.

Step 1 — Configure in vite.config.ts:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith("fluent-"),
        },
      },
    }),
  ],
});

Step 2 — Register in main.ts:

import {
  provideFluentDesignSystem,
  fluentButton,
  fluentCard,
  fluentTextField,
} from "@fluentui/web-components";

provideFluentDesignSystem().register(
  fluentButton(),
  fluentCard(),
  fluentTextField()
);

Step 3 — Use in templates with v-bind and v-on:

<template>
  <fluent-design-system-provider :accent-base-color="brandColor">
    <fluent-text-field
      :placeholder="'Enter name'"
      @change="onNameChange"
    ></fluent-text-field>

    <fluent-button
      appearance="accent"
      :disabled="isSubmitting"
      @click="handleSubmit"
    >
      Submit
    </fluent-button>
  </fluent-design-system-provider>
</template>

<script setup lang="ts">
import { ref } from "vue";

const brandColor = ref("#0078d4");
const isSubmitting = ref(false);

function onNameChange(e: Event) {
  console.log((e.target as HTMLInputElement).value);
}

function handleSubmit() {
  isSubmitting.value = true;
}
</script>

6.4 Svelte

Svelte treats unknown HTML tags as custom elements natively.

Step 1 — Register in main.ts or +layout.ts:

import {
  provideFluentDesignSystem,
  fluentButton,
  fluentCard,
  fluentTextField,
} from "@fluentui/web-components";

provideFluentDesignSystem().register(
  fluentButton(),
  fluentCard(),
  fluentTextField()
);

Step 2 — Use in .svelte files:

<script lang="ts">
  let name = "";
  let submitting = false;

  function handleChange(e: Event) {
    name = (e.target as HTMLInputElement).value;
  }

  function submit() {
    submitting = true;
    console.log("Submitted:", name);
  }
</script>

<fluent-design-system-provider accent-base-color="#0078d4" base-layer-luminance="1">
  <fluent-card>
    <h2>Registration</h2>
    <fluent-text-field placeholder="Full name" on:change={handleChange}></fluent-text-field>
    <fluent-button appearance="accent" disabled={submitting} on:click={submit}>
      Register
    </fluent-button>
  </fluent-card>
</fluent-design-system-provider>

<style>
  fluent-card {
    padding: 20px;
    max-width: 400px;
  }
</style>

Svelte compiler note: If Svelte warns about unknown elements, add to svelte.config.js:

export default {
  compilerOptions: {
    customElement: false, // app is NOT a custom element itself
  },
  // Svelte 4+: no extra config needed for consuming custom elements
};

7. FAST Foundation

Fluent Web Components are built on FAST (@microsoft/fast-element), Microsoft's custom element authoring platform. Understanding FAST helps when extending or creating custom Fluent-compatible components.

Core FAST concepts

Creating a custom FAST element

import { FASTElement, customElement, attr, html, css } from "@microsoft/fast-element";

const template = html<MyAlert>`
  <div class="alert ${(x) => x.severity}">
    <slot></slot>
    <button @click="${(x) => x.dismiss()}">×</button>
  </div>
`;

const styles = css`
  :host {
    display: block;
    padding: 12px;
    border-radius: var(--control-corner-radius, 4px);
  }
  .info { background: var(--accent-fill-rest); color: white; }
  .warning { background: #fff3cd; color: #856404; }
  .error { background: #f8d7da; color: #721c24; }
`;

@customElement({ name: "my-alert", template, styles })
export class MyAlert extends FASTElement {
  @attr severity: "info" | "warning" | "error" = "info";

  dismiss() {
    this.$emit("dismissed");
    this.remove();
  }
}

FAST template bindings

8. Theming

Brand color theming

Map your brand to the Fluent palette by setting accent-base-color:

<!-- Microsoft blue (default) -->
<fluent-design-system-provider accent-base-color="#0078d4"></fluent-design-system-provider>

<!-- Custom green brand -->
<fluent-design-system-provider accent-base-color="#107c10"></fluent-design-system-provider>

<!-- Custom orange brand -->
<fluent-design-system-provider accent-base-color="#ff8c00"></fluent-design-system-provider>

The design system automatically derives an entire palette (hover, pressed, focus states) from the base color.

Teams theme mapping

To match Microsoft Teams themes in Web Components:

const teamsThemes = {
  default: { accent: "#6264A7", luminance: 1 },
  dark: { accent: "#6264A7", luminance: 0.15 },
  highContrast: { accent: "#FFFF00", luminance: 0 },
};

function applyTeamsTheme(themeName) {
  const provider = document.querySelector("fluent-design-system-provider");
  const theme = teamsThemes[themeName];
  provider.setAttribute("accent-base-color", theme.accent);
  provider.setAttribute("base-layer-luminance", String(theme.luminance));
}

High contrast support

Web Components respect the OS forced-colors mode via CSS forced-colors media query. The FAST foundation handles this automatically. To test:

@media (forced-colors: active) {
  /* Override styles for Windows High Contrast Mode */
  :host {
    border: 1px solid ButtonText;
  }
}

CSS custom property override at component level

<fluent-button
  style="--accent-fill-rest: #107c10; --accent-fill-hover: #0e6b0e;"
  appearance="accent"
>
  Green Override
</fluent-button>

9. Accessibility

ARIA in Shadow DOM

Custom elements use Shadow DOM, which creates challenges for ARIA references (e.g., aria-labelledby pointing to an element in the light DOM). Fluent Web Components handle this via:

1. Delegated focus — delegatesFocus: true on shadow root
2. ARIA reflection — Attributes set on the host are forwarded into the shadow root
3. Slot-based labeling — Named slots allow label association

<!-- Correct: label association via slot -->
<fluent-field label-position="above">
  <label slot="label">Username</label>
  <fluent-text-field slot="input" required></fluent-text-field>
</fluent-field>

Keyboard navigation patterns

Focus management

// Move focus into a dialog after opening
const dialog = document.querySelector("fluent-dialog");
dialog.hidden = false;
dialog.focus(); // trap-focus handles the rest

// Return focus after dialog closes
dialog.addEventListener("dismiss", () => {
  triggerButton.focus();
});

Screen reader testing checklist

• Every interactive control announces its role and label
• State changes (checked, expanded, selected) are announced
• Error messages are linked via aria-describedby or live regions
• Data grid announces row/column position
• Dialog announces its title on open
• Loading spinners use aria-busy and aria-label

10. Cross-references

Reference files

• Component catalog (full): ${CLAUDE_PLUGIN_ROOT}/skills/fluent-web-components/references/web-components-catalog.md
• Core component catalog (React): ${CLAUDE_PLUGIN_ROOT}/skills/fluent-design-system/references/component-catalog.md
• Token reference: ${CLAUDE_PLUGIN_ROOT}/skills/fluent-design-system/references/token-reference.md

Command

To scaffold a new Web Component integration:

/fluent-ui-design:web-component <component-name> --framework=<vanilla|angular|vue|svelte>