import { Meta } from '@storybook/addon-docs/blocks';

V2 → V3 Migration Guide

We're happy to announce Fluent Web Components v3 is now available. This document provides a high-level overview of the differences and API changes between previous versions. Please reach out if you have any questions.

Here's a snapshot of what's new and improved in v3.

• Smaller bundle size (-26% compressed!)
• Reduced DOM size and overhead by nearly 50%
• Improved Storybook docs
• Updated to FASTElement v2.0
• Individual component exports
• Leveraging ElementInternals for better form support
• Removed hard dependency on @microsoft/fast-foundation
• Continued alignment with Fluent React v9
• Improved setTheme() to set/unset at the page or element level

Component Comparison v2 → v3

A high-level look at the differences between components in v2 and v3

• 🆕 15 new components
• ⚠️ 5 renamed components
• ⛔️ 4 deprecated components
• 🛣️ 13 components on our current roadmap

Renamed Components

• anchor = use link or anchor-button
• progress = use progress-bar
• select = use dropdown
• text-area = textarea
• text-field = text-input

Deprecated Components

• anchored-region
• slider-label = use field, label
• tabs = use tablist
• tab-panel = use role="tabpanel"

API Changes

• Form controls now use <fluent-field> wrapper to handle label spacing and errors
• Dialog = requires Dialog Body child
• Tabs = no longer a uniform control, allows for flexibility
• Accordion Item = attribute changes
• RadioGroup = new API to leverage field

API changes, renames, and deprecations are itemized in the table below.

Notable API Changes

Here's an overview of the more significant changes in the project. Other smaller changes (like attribute renaming) will be reflected in the improved Storybook docs.

Anchor

Anchor is deprecated in favor of <fluent-link> (for text links) and <fluent-anchor-button> (for links that look like buttons).

Dialog

The previous dialog didn't allow for expressive dialogs without the default padding and presentation (like full-width imagery). This introduction of the <fluent-dialog-body> element allows for more custom compositions.

BEFORE:

<!-- V2 -->
<fluent-dialog>
  <h1 slot="title">Title goes here</h1>
  
  Contents go here
</fluent-dialog>

AFTER:

<!-- V3 -->
<fluent-dialog>
  
  <fluent-dialog-body>
    <h1 slot="title">Title goes here</h1>
    Contents go here
  </fluent-dialog-body>
</fluent-dialog>

Field

We have a new form Field component to control label placement and validation errors for form controls.

<fluent-field label-position="after">
  <fluent-checkbox slot="input"></fluent-checkbox>

  <label slot="label" for="checkbox">Label goes here</label>
</fluent-field>

This is also used by <fluent-radio-group> (see below).

Due to web platform labelling constraints of the ShadowDOM, the labelling API for <fluent-text-input> and <fluent-textarea> is slightly different. Note that <fluent-text-input> uses the default slot for label, while <fluent-textarea> uses the label slot due to its default slot is reserved for the content inside the text area.

<fluent-text-input>
  <fluent-label>Label goes here</fluent-label>
</fluent-text-input>

<fluent-textarea>
  <fluent-label slot="label">Label goes here</fluent-label>
</fluent-textarea>

RadioGroup

BEFORE:

<fluent-radio-group id="radio-group">
  <fluent-radio value="apple">Apple</fluent-radio>
  <fluent-radio value="banana">Banana</fluent-radio>
</fluent-radio-group>

AFTER:

<fluent-field>
  <label slot="label" for="radio-group">Favorite Fruit</label>
  <fluent-radio-group
    slot="input"
    id="radio-group"
    aria-labelledby="radio-group--label"
    orientation="vertical"
    name="favorite-fruit"
  >
    <fluent-field label-position="after">
      <label slot="label" for="radio-group--apple">Apple</label>
      <fluent-radio slot="input" id="radio-group--apple" name="favorite-fruit" value="apple"></fluent-radio>
    </fluent-field>

    <fluent-field label-position="after">
      <label slot="label" for="radio-group--banana">Banana</label>
      <fluent-radio slot="input" id="radio-group--banana" name="favorite-fruit" value="banana"></fluent-radio>
    </fluent-field>
  </fluent-radio-group>
</fluent-field>

setTheme

A more powerful and simpler set-theme API that allows setting themes at the element level.

• setThemeFor() is deprecated in favor of setTheme( theme, element )
• setTheme() can unset themes with setTheme(null) or setTheme( null, element )

Case studies

• Edge is seeing impressive results when switching WebView UI to Fluent Web Components v3.