Skip to content

docs: clarify FAST Element v3 browser feature support #7541

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
janechu wants to merge 1 commit into
base: releases/fast-element-v3
Choose a base branch
from
+41 −5
Draft

docs: clarify FAST Element v3 browser feature support #7541

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 41 additions & 5 deletions sites/website/src/docs/3.x/resources/browser-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,21 @@ eleventyNavigation:
title: Browser Support
navigationOptions:
activeKey: browser-support3x
description: View the list of browsers that have native support for the Web Components features and native globalThis required by fast-element v3.
description: View browser and application support guidance for FAST Element v3 features, fallbacks, and optional SSR/hydration capabilities.
keywords:
- browser support
---

The following browsers have native support for the Web Components features used by `@microsoft/fast-element`, including the native `globalThis` required by v3:
FAST Element v3 builds on native web platform features. The baseline
client-rendered runtime expects autonomous custom elements, Shadow DOM, and
native `globalThis` support. Optional capabilities, such as Declarative Shadow
DOM hydration and constructable stylesheets, use newer browser features when
they are available.

## Baseline runtime support

The following browser versions have native support for the baseline features used
by client-rendered `@microsoft/fast-element` components:

* Microsoft Edge 79+
* Mozilla Firefox 65+
Expand All @@ -27,6 +36,33 @@ The following browsers have native support for the Web Components features used
* Firefox for Android 68+
* Samsung Internet 10.0+

FAST Element v3 no longer polyfills `globalThis` for older engines. If you need
to support an environment below these minimums, load a `globalThis` polyfill
before importing FAST.
FAST Element v3 does not include platform polyfills. If an application must run
below these minimums, load standards-compatible polyfills before importing FAST.

## Feature support matrix

| Feature | Browser support guidance | Fallback and application requirements |
|---|---|---|
| Web Components / custom elements | Supported by the baseline browsers above for autonomous custom elements. FAST Element does not use customized built-in elements. | No FAST fallback. Browsers must provide native custom elements, or the application must load compatible platform polyfills before defining FAST elements. |
| Shadow DOM | Supported by the baseline browsers above. FAST creates an open shadow root by default for templates and style encapsulation. | No FAST Shadow DOM polyfill. Components that intentionally set `shadowOptions: null` can render to light DOM, but default FAST Element authoring expects browser Shadow DOM support. |
| Declarative Shadow DOM | Optional for client-only rendering. Hydration requires browser support for `<template shadowrootmode>`, such as Chrome/Edge 111+, Firefox 123+, Safari/iOS Safari 16.4+, Opera 97+, Samsung Internet 22+, and current Chromium-based mobile browsers. | FAST hydrates an existing shadow root; it does not make unsupported browsers parse Declarative Shadow DOM. Older browsers need an application-level DSD transform/polyfill before components connect, or they should use client rendering. |
| `adoptedStyleSheets` / constructable stylesheets | Supported in Chrome 73+, Edge 79+, Firefox 101+, Safari/iOS Safari 16.4+, Opera 60+, Samsung Internet 11.1+, and current Chromium-based mobile browsers. | FAST falls back to injected `<style>` elements for string-based `css` styles when adopted stylesheets are unavailable. Passing `CSSStyleSheet` instances directly requires browser constructable stylesheet support. |
| Trusted Types | Not part of the FAST Element baseline. Available in Chromium-based browsers such as Chrome/Edge 83+, Opera 69+, Samsung Internet 13+, and newer Firefox and Safari releases. | FAST creates a Trusted Types policy when `globalThis.trustedTypes` exists and otherwise uses its string-based DOM policy. Apps that enforce `require-trusted-types-for` must configure an appropriate DOM policy before templates compile. |
| `globalThis` | Required by FAST Element v3. The baseline versions above include native `globalThis` support. | FAST Element v3 no longer polyfills `globalThis`. Load a `globalThis` polyfill before importing FAST in older browsers or non-browser runtimes. |

## SSR and hydration notes

Client-rendered FAST Element components only need the baseline runtime features.
Server-side rendering and hydration add browser and application requirements:

* The server must emit FAST-compatible hydration markers and Declarative Shadow
DOM templates.
* The browser must parse Declarative Shadow DOM before FAST elements connect.
* The application must call `enableHydration()` from
`@microsoft/fast-element/hydration.js` before hydrated elements connect.
* If hydration is not enabled, or if a template is not hydratable, FAST uses
client-side rendering for the element.

Use client rendering, or provide an application-owned DSD transform/polyfill, for
browsers that meet the baseline runtime requirements but do not support
Declarative Shadow DOM.