diff --git a/sites/website/src/docs/3.x/resources/browser-support.md b/sites/website/src/docs/3.x/resources/browser-support.md index 427583d08a8..c84ae616020 100644 --- a/sites/website/src/docs/3.x/resources/browser-support.md +++ b/sites/website/src/docs/3.x/resources/browser-support.md @@ -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+ @@ -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 `