#6649·core

Stencil FOUC styles should use @layer to avoid cascade conflicts with React 19

Author: estevaolucasCreated Mar 25, 2026Updated Jun 18, 2026

LabelsStencil v5

Summary

Stencil's FOUC prevention CSS (<style data-styles>) can override consumer CSS when used with React 19, because React 19 reorders <head> elements and changes the cascade order. Wrapping the FOUC styles in @layer would make them lowest-priority by default, fixing the conflict without requiring consumers to patch Stencil.

Current behavior

In bootstrap-lazy.ts, Stencil injects a <style data-styles> tag into <head> with:

css

market-component-a, market-component-b, ... { visibility: hidden }
[hydrated] { visibility: inherit }

It's inserted via:

javascript

head.insertBefore(dataStyles, metaCharset ? metaCharset.nextSibling : head.firstChild);

This relies on source order in <head> — the FOUC styles are placed early so that component-specific and consumer CSS loaded later will override them.

Problem with React 19

React 19 introduced "hoistable" style management — it moves <link rel="stylesheet"> tags to head.firstChild. This pushes <meta charset> down in the head, so when Stencil inserts after metaCharset.nextSibling, the FOUC styles end up after component CSS <link> tags instead of before them.

The result: [hydrated] { visibility: inherit } and consumer class selectors (e.g. .popover { visibility: hidden }) have equal specificity (0,1,0). With the FOUC style now later in source order, it wins — causing components to inherit visibility: hidden from ancestors even after hydration.

This caused a production incident at Square where Market web component popovers became invisible but still captured pointer events, blocking user interaction across the entire dashboard.

Proposed fix

Wrap the FOUC CSS in @layer:

diff

// src/runtime/bootstrap-lazy.ts
- dataStyles.textContent += cmpTags + HYDRATED_CSS;
+ dataStyles.textContent += `@layer stencil-hydration{${cmpTags}${HYDRATED_CSS}}`;

Per the CSS cascade spec, layered styles always lose to unlayered styles, regardless of source order or specificity. This is semantically correct — Stencil's FOUC styles are intentionally low-priority defaults that should yield to any consumer CSS.

Why `@layer` is the right solution

Order-independent: Works regardless of where the <style> tag lands in <head>
Semantically correct: FOUC styles are defaults, not overrides
No consumer changes needed: Consumers don't need to patch Stencil
Framework-agnostic: Fixes the issue for React 19 and any future framework that reorders <head>
Browser support: @layer is supported in all modern browsers (Chrome 99+, Firefox 97+, Safari 15.4+). Older browsers silently discard @layer blocks — but the FOUC bug only manifests with React 19 which itself requires modern browsers

Workaround

We're currently working around this by patching Stencil's output at runtime with a MutationObserver that wraps <style data-styles> content in @layer stencil-hydration { ... } before MFEs load.

Environment

Stencil: 4.18.0
React: 19.x
Output target: dist-custom-elements (via @stencil/react-output-target)

Source: stenciljs/core

View original on GitHub View discussion on GitHub