Web Component FOUC (Flash of unstyled content)

Web Components (custom elements) are 100% defined in JavaScript. That includes their HTML and CSS. Those are programmatically added to the DOM through APIs. By the time the browser has interpreted and executed that code, there is a good chance that the rendering pipeline has already put the custom element on the screen. Since it doesn't know about the element the first time around it will render it without the intended styling. After the JavaScript of the custom element definition is executed and the browser, therefore, knows about the CSS rules that apply to that element it can update the view.

Flash of unstyled content (FOUC) can cause irritating layout shifts as well as reveal content that should have been progressively disclosed.

Quick Fix

To prevent FOUC you can deploy one of the following two quick fixes by adding the appropriate snippet in a style tag to the head of the page. In this scenario, our custom element will be defined with the tag name my-component.

Choose the following snippet if the content of your component is hidden by default. For example a tooltip.

  my-component:not(:defined) {
  display: none;
}

Choose the following snippet if the content of your component is visible by default. For example a button.

  my-component:not(:defined) {
  visibility: hidden;
}

Explanation

display: none removes the element from the layout of the page. Therefore it will not affect any other elements. visibility: hidden only hides the element but keeps it in the layout. Therefore space is reserved for this element.

:not(:defined) is a combination of two CSS pseudo-classes that will target an element that is currently unknown (undefined) to the browser. When the custom element is defined by calling define on the registry, that element is known to the browser and the pseudo-class won't target it anymore.

If you would like your components to fade in you can replace visibility: hidden with opacity: 0 and add a transition to the opacity inside your custom elements CSS like this: transition: opacity 0.3s ease-in.

Critical, specific styling upfront

The above two snippets are labeled "Quick fix" since they do help but aren't perfect. The best way to achieve no FOUC is to tell the browser upfront about the CSS it needs to properly layout your component. This should be properties like display (e.g. is it inline or is it block) and information about the size like width and height.

For each of your custom elements collect the necessary CSS that the browser needs to know when it first encounters the element to prevent FOUC, and place it in the head of the page. Ideally, you would want to do this in a way where you aren't putting all of the "potentially" necessary CSS in the head but only the rules that apply to elements that will be visible to the user before the browser had a chance to define the custom element properly.