Skip to content

Follow-ups on shadowrootadoptedstylesheets #1287

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

Open
KurtCattiSchmidt wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Follow-ups on shadowrootadoptedstylesheets #1287

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
618050d
Initial commit
KurtCattiSchmidt Mar 26, 2026
47fe4ee
onerror *attribute*
KurtCattiSchmidt Mar 26, 2026
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
6 changes: 3 additions & 3 deletions ShadowDOM/explainer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ An inline CSS module script could also be imported in a JavaScript module in the
```html
import styles from 'foo' with { type: 'css' };
```
Another advantage of this proposal is that it can allow multiple module specifiers in the `shadowrootadoptedstylesheets` property:
Another advantage of this proposal is that it can allow multiple module specifiers in the `shadowrootadoptedstylesheets` attribute:
```html
<style type="module" specifier="foo">
#content {
Expand Down Expand Up @@ -406,7 +406,7 @@ import sheet from "foo" with { type: "css" };
shadowRoot.adoptedStyleSheets = [sheet];
```

...assuming that "foo" hasn't been used as the key of an [import map](https://html.spec.whatwg.org/multipage/webappapis.html#import-maps) that redirects it to a URL. If "foo" has used as a key of an [import map](https://html.spec.whatwg.org/multipage/webappapis.html#import-maps) that redirects to a URL, that URL will be fetched instead of locating the declarative version.
...assuming that "foo" hasn't been used as the key of an [import map](https://html.spec.whatwg.org/multipage/webappapis.html#import-maps) that redirects it to a URL. If "foo" has been used as a key of an [import map](https://html.spec.whatwg.org/multipage/webappapis.html#import-maps) that redirects to a URL, that URL will be fetched instead of locating the declarative version.

If a module is imported imperatively in this fashion and the Declarative CSS Module is not in the [module map](https://html.spec.whatwg.org/#module-map), the import fails, even if it is added declaratively at a later time.

Expand Down Expand Up @@ -712,7 +712,7 @@ A challenge that arises is dealing with scopes and idrefs. If a declarative styl

The script version of this already exists via the [adoptedStyleSheets](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets) property:
```html
import sheet from './styles.css' assert { type: 'css' }; // or new CSSStyleSheet();
import sheet from './styles.css' with { type: 'css' }; // or new CSSStyleSheet();
shadowRoot.adoptedStyleSheets = [sheet];
```

Expand Down
6 changes: 3 additions & 3 deletions ShadowDOMAdoptedStyleSheets/explainer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,11 +177,11 @@ This means the following example will work, even without a preceding `<link rel=

The shadow root is initially rendered without the styles from "foo.css". Once the fetch completes, the styles are applied. This will cause a FOUC (Flash of Unstyled Content) — the element is first painted without the external styles and then repainted once the fetch completes.

Developers should pre-fetch external CSS using [`<link rel="modulepreload">`](https://html.spec.whatwg.org/multipage/links.html#link-type-modulepreload) to ensure it's in the module map before the `<template>` is parsed, avoiding FOUC and providing error handling:
Developers should pre-fetch external CSS using [`<link rel="modulepreload">`](https://html.spec.whatwg.org/multipage/links.html#link-type-modulepreload) to initiate the fetch before the `<template>` is parsed. If the fetch completes before the `<template>` tag is parsed, the styles will be immediately populated. The optional `blocking="render"` attribute will block rendering until the fetch completes, avoiding FOUC if desired. The `onerror` may also provide error handling:
Copy link
Copy Markdown
Member

@dandclark dandclark Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Developers should pre-fetch external CSS using [`<link rel="modulepreload">`](https://html.spec.whatwg.org/multipage/links.html#link-type-modulepreload) to initiate the fetch before the `<template>` is parsed. If the fetch completes before the `<template>` tag is parsed, the styles will be immediately populated. The optional `blocking="render"` attribute will block rendering until the fetch completes, avoiding FOUC if desired. The `onerror` may also provide error handling:
Developers should pre-fetch external CSS using [`<link rel="modulepreload">`](https://html.spec.whatwg.org/multipage/links.html#link-type-modulepreload) to initiate the fetch before the `<template>` is parsed. If the fetch completes before the `<template>` tag is parsed, the styles will be immediately populated. The optional `blocking="render"` attribute will block rendering until the fetch completes, avoiding FOUC if desired. The `onerror` attribute may also provide error handling:


```html
<head>
<link rel="modulepreload" as="style" href="./foo.css" onerror="handleError()">
<link rel="modulepreload" as="style" href="./foo.css" onerror="handleError()" blocking="render">
</head>
...
<div>
Expand All @@ -204,7 +204,7 @@ The fetch fallback has an important limitation: **there is no way to catch fetch

For this reason, developer tools should surface a warning when `shadowrootadoptedstylesheets` triggers a fetch, recommending that developers either:
1. Define the styles inline using `<style type="module" specifier="...">` (a [Declarative CSS Module](../ShadowDOM/explainer.md#proposal-inline-declarative-css-module-scripts)) so the styles are available synchronously, or
2. Use `<link rel="modulepreload">` to pre-fetch the module, which supports error handling via the `onerror` event and can be combined with [`blocking="render"`](https://html.spec.whatwg.org/multipage/urls-and-fetching.html#blocking-attributes) to avoid FOUC.
2. Use `<link rel="modulepreload">` to pre-fetch the module, which can be combined with [`blocking="render"`](https://html.spec.whatwg.org/multipage/urls-and-fetching.html#blocking-attributes) to avoid FOUC.
Comment on lines 205 to +207
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This recommendation bullet removed the earlier claim about onerror error handling, but the example above still includes onerror="handleError()" and the preceding text mentions it. Please make the guidance consistent (either mention error handling here as well, or remove/de-emphasize onerror in the earlier paragraph/example if it’s not intended as a recommendation).

Copilot uses AI. Check for mistakes.

The order of `shadowrootadoptedstylesheets` reflects the order in the underlying `adoptedStyleSheets` array, which may impact the final application of CSS rules, as they are applied [in array order](https://drafts.csswg.org/cssom/#css-style-sheet-collections). Since fetch completion order may not match the specified order, each fetch completion could trigger a separate FOUC.

Expand Down
Loading