Module Stylesheet <link> tags by KurtCattiSchmidt · Pull Request #12339 · whatwg/html

KurtCattiSchmidt · 2026-04-06T19:00:19Z

Adds support for <link type=module rel=stylesheet>.

At least two implementers are interested (and none opposed):
- Chromium
- …
[] Tests are written and can be reviewed and commented upon at:
Implementation bugs are filed:
- Chromium: https://issues.chromium.org/issues/448174611
- Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=2037650
- WebKit: https://bugs.webkit.org/show_bug.cgi?id=314242
- Deno (only for timers, structured clone, base64 utils, channel messaging, module resolution, web workers, and web storage): …
- Node.js (only for timers, structured clone, base64 utils, channel messaging, and module resolution): …
Corresponding HTML AAM & ARIA in HTML issues & PRs: N/A
MDN issue is filed: Module Stylesheet <link> tags mdn/mdn#824
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

Addresses #10673

/indices.html ( diff )
/links.html ( diff )
/semantics.html ( diff )
/webappapis.html ( diff )

noamr · 2026-04-16T16:36:27Z

From an initial look this seems to be on the right track. I need to spend some time on the details though.
cc @emilio

noamr · 2026-04-16T19:31:46Z

Right now all of the shadowroot* properties map to attachShadow({}) properties. Do we want to add adoptedStyleSheets to ShadowRootInit?

Note that the current properties of ShadowRootInit become read only on the ShadowRoot, unlike adoptedStylesheets whch is a mutable array-like thing.

So I think it might be nice to include it in the init dictionary but I could also see why it's not necessary.

KurtCattiSchmidt · 2026-04-22T22:03:33Z

Right now all of the shadowroot* properties map to attachShadow({}) properties. Do we want to add adoptedStyleSheets to ShadowRootInit?

Agreed with @noamr's response here - since there's already an adoptedStyleSheets property on the imperative version that references a mutable array, we don't need to add it again to ShadowRootInit.

Think of shadowrootadoptedstylesheets as a purely declarative thing, since it's lacking in the declarative version but present in the imperative version.

emilio

Question, might be me misunderstanding CSS modules, but I'd figure I'd ask...

This change updates the fetch behavior to match whatwg/html#12339. Note that this modifies the code for existing import, import(), and modulepreload for consistency, but the existing behavior for these API's does *not* change in any circumstance. The only observable change is in the shadowrootadoptedstylesheets fetching behavior. By modifying the CSS module fetching to first create the CSSStyleSheet before fetching and calling replaceSync upon completion, we are able to remove the placeholder stylesheets that were being inserted for shadowrootadoptedstylesheets. This simplifies the logic considerably and will be more performant. Unlike the other API's for fetching a CSS Module Script, shadowrootadoptedstylesheets will leave behind an empty CSSStyleSheet in adoptedStyleSheets if the fetch fails. This simplifies the logic and seems like a reasonable trade off for a rare condition. Earlier versions of this CL removed it upon failure, but the implementation was considerably more complex and had other side effects. Change-Id: If00445458983f5062a1ca2d83ed0253cc171d1ff Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7709812 Reviewed-by: Dan Clark <daniec@microsoft.com> Commit-Queue: Kurt Catti-Schmidt <kschmi@microsoft.com> Cr-Commit-Position: refs/heads/main@{#1629010}

…a=testonly Automatic update from web-platform-tests [CSS Modules] Update fetching strategy This change updates the fetch behavior to match whatwg/html#12339. Note that this modifies the code for existing import, import(), and modulepreload for consistency, but the existing behavior for these API's does *not* change in any circumstance. The only observable change is in the shadowrootadoptedstylesheets fetching behavior. By modifying the CSS module fetching to first create the CSSStyleSheet before fetching and calling replaceSync upon completion, we are able to remove the placeholder stylesheets that were being inserted for shadowrootadoptedstylesheets. This simplifies the logic considerably and will be more performant. Unlike the other API's for fetching a CSS Module Script, shadowrootadoptedstylesheets will leave behind an empty CSSStyleSheet in adoptedStyleSheets if the fetch fails. This simplifies the logic and seems like a reasonable trade off for a rare condition. Earlier versions of this CL removed it upon failure, but the implementation was considerably more complex and had other side effects. Change-Id: If00445458983f5062a1ca2d83ed0253cc171d1ff Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7709812 Reviewed-by: Dan Clark <daniec@microsoft.com> Commit-Queue: Kurt Catti-Schmidt <kschmi@microsoft.com> Cr-Commit-Position: refs/heads/main@{#1629010} -- wpt-commits: e564867fbfe3cc70cc8d43ddac392b7b848bc7e4 wpt-pr: 59805

…a=testonly Automatic update from web-platform-tests [CSS Modules] Update fetching strategy This change updates the fetch behavior to match whatwg/html#12339. Note that this modifies the code for existing import, import(), and modulepreload for consistency, but the existing behavior for these API's does *not* change in any circumstance. The only observable change is in the shadowrootadoptedstylesheets fetching behavior. By modifying the CSS module fetching to first create the CSSStyleSheet before fetching and calling replaceSync upon completion, we are able to remove the placeholder stylesheets that were being inserted for shadowrootadoptedstylesheets. This simplifies the logic considerably and will be more performant. Unlike the other API's for fetching a CSS Module Script, shadowrootadoptedstylesheets will leave behind an empty CSSStyleSheet in adoptedStyleSheets if the fetch fails. This simplifies the logic and seems like a reasonable trade off for a rare condition. Earlier versions of this CL removed it upon failure, but the implementation was considerably more complex and had other side effects. Change-Id: If00445458983f5062a1ca2d83ed0253cc171d1ff Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7709812 Reviewed-by: Dan Clark <daniecmicrosoft.com> Commit-Queue: Kurt Catti-Schmidt <kschmimicrosoft.com> Cr-Commit-Position: refs/heads/main{#1629010} -- wpt-commits: e564867fbfe3cc70cc8d43ddac392b7b848bc7e4 wpt-pr: 59805 UltraBlame original commit: 04a038fe6e54a754c927f29afe85d3c66476f8a3

yoavweiss · 2026-07-26T09:53:09Z

@KurtCattiSchmidt - While implementing #10327 in Chromium, I've noticed some failing tentative tests related to this PR that I believe would need to change, given the new behavior of failed module loads.

shadowrootadoptedstylesheets-async-fetch-failure-shared.html and shadowrootadoptedstylesheets-modulepreload-failure.html both assume that a failed fetch is permanent, when that's no longer the case. I believe we'd need to change these tests, and any relevant spec language.

…rializable, and failed fetch behavior

noamr

Really nice work, see comments!

noamr · 2026-08-25T15:07:49Z

I think we can make it so that specifiers used in href like this also have to be valid URLs as far as conformance goes.
It's mostly a single word or something which is a valid URL to begin with. Then this is just a URL with using module-specifier for relative resolution rather than ordinary URL resolution

(this is an opinion btw, and the whole "href can be a specifier" notion should be discussed with a wider community)

noamr · 2026-08-25T15:12:33Z

-  <code>link</code> element, then <dfn id="the-link-is-an-alternative-stylesheet">the link is an
-  alternative style sheet</dfn>; in this case, the <code data-x="attr-title">title</code> attribute
-  must be specified on the <code>link</code> element, with a non-empty value.</p>
+  <code>link</code> element and the element is not a <span>module stylesheet link</span>, then <dfn


This is another cardinality issue - on regular <link rel=stylesheet>, the title attribute on link goes straight to the StyleSheet.title value: https://drafts.csswg.org/cssom/#dom-stylesheet-title. alternate works for selecting which alternate stylesheet and has similar cardinality issues.

Unlike media and disabled, we can't handle it at the element level instead, since it needs to interact with the stylesheet and a browser UI setting.

I assumed these were unofficially deprecated, as Chrome doesn't support them. But it looks like Firefox still does support them, so I'm curious what their thoughts are on this. I think for now, removing this exception for link modules makes sense, as it won't impact interop.

keithamus · 2026-08-28T08:00:58Z

This used to be the PR for adoptedStyleSheets, it seems like it's now for modules in <link>. Is it worth raising a new PR? All of the prior comments are now outdated as they talk about a significantly different concept.

emilio

Curious, so the current state of the PR defines <link import=""> rather than using type="module". Not objecting or anything, but why?

Would it be possible to share more of the processing model (specially the fetching etc, and the load event firing) with the current href version? I assume that's roughly how it would work, implementation-wise.

emilio · 2026-08-28T09:40:14Z

+       <li><p>Set <var>el</var>'s <span data-x="link module CSS style sheet">module CSS style
+       sheet</span> to <var>sheet</var>, and <span
+       data-x="concept-event-fire">fire an event</span> named <code
+       data-x="event-load">load</code> at <var>el</var>.</p></li>


Link load events generally fire async, probably this should use a task.

noamr · 2026-08-28T09:45:50Z

Curious, so the current state of the PR defines <link import=""> rather than using type="module". Not objecting or anything, but why?

This came up at WHATNOT, as wanting to keep type for mime-types in links, and also some issues with having a module specifier instead of a URL in href.

By using <link import="" href="url.css"> or <link import="specifier" href="url.css">, the link would act as a regular stylesheet in unsupported browsers, and as a module when supported.

annevk · 2026-08-28T14:30:01Z

To be clear, I don't think we ended up really reaching a conclusion about the design of this feature at WHATNOT. Perhaps we should first flesh out some of the alternatives in a design document. And I second @keithamus's request for closing this PR as that just makes reviewing unwieldy.

KurtCattiSchmidt · 2026-08-28T17:08:48Z

@annevk - for context, there is a design document that we discussed at a two hour joint WHATWG-CSSWG meeting a few weeks ago. Minutes are here.

Members of Mozilla, Webkit, and Blink were present and we jointly agreed that <link> was the best approach for this scenario.

The suggestion to use <style> yesterday wasn't explored at that discussion, but I just added it to the document with pros and cons. Feel free to edit the document as you see fit. As-is, I don't think the arguments in favor of <style> are compelling over <link>, but I may have missed some. I'm happy to discuss this and get consensus though. I'm very curious what @jakearchibald and @keithamus think of <style> over <link>.

Agreed that the history makes this confusing. I'll open a new PR.

KurtCattiSchmidt · 2026-08-28T22:31:54Z

This used to be the PR for adoptedStyleSheets, it seems like it's now for modules in <link>. Is it worth raising a new PR? All of the prior comments are now outdated as they talk about a significantly different concept.

New PR is at #12860

annevk · 2026-08-29T08:27:01Z

I might be missing something but I don't see anyone from WebKit in the list of attendees there? But also, WHATWG only makes tentative decisions during meetings so it doesn't really matter.

noamr · 2026-08-29T09:36:34Z

I might be missing something but I don't see anyone from WebKit in the list of attendees there? But also, WHATWG only makes tentative decisions during meetings so it doesn't really matter.

@rniwa was there (not that that makes the conclusions binding)

KurtCattiSchmidt requested a review from dandclark April 7, 2026 17:03

KurtCattiSchmidt added the agenda+ To be discussed at a triage meeting label Apr 8, 2026

This comment was marked as outdated.

Sign in to view

zcorpan mentioned this pull request Apr 20, 2026

Upcoming WHATNOT meeting on 2026-04-16 #12370

Closed

emilio reviewed Apr 22, 2026

View reviewed changes

Comment thread source Outdated

KurtCattiSchmidt mentioned this pull request Apr 29, 2026

Upcoming WHATNOT meeting on 2026-04-30 #12401

Closed

jstenback removed the agenda+ To be discussed at a triage meeting label Apr 30, 2026

This was referenced May 6, 2026

Declarative CSS Modules #11687

Open

Upcoming WHATNOT meeting on 2026-05-07 #12413

Closed

noamr reviewed May 7, 2026

View reviewed changes

Comment thread source

Comment thread source Outdated

chromium-wpt-export-bot mentioned this pull request May 12, 2026

[CSS Modules] Update fetching strategy web-platform-tests/wpt#59805

Merged

KurtCattiSchmidt mentioned this pull request Jun 10, 2026

Style Module Imports via <link> Elements WebKit/standards-positions#407

Open

KurtCattiSchmidt mentioned this pull request Jun 22, 2026

Style Module Imports via <link> Elements mozilla/standards-positions#1081

Open

KurtCattiSchmidt mentioned this pull request Jul 2, 2026

shadowrootadoptedstylesheets on HTMLTemplateElement web-platform-dx/web-features#4148

Open

jakearchibald reviewed Aug 5, 2026

View reviewed changes

Comment thread source Outdated

Comment thread source Outdated

jakearchibald reviewed Aug 5, 2026

View reviewed changes

Comment thread source Outdated

Initial commit

40b9b7c

KurtCattiSchmidt force-pushed the sas-fetch branch from 3897188 to 46ba117 Compare August 24, 2026 22:28

KurtCattiSchmidt changed the title ~~shadowrootadoptedstylesheets on <template>~~ Module Stylesheet <link> tags Aug 24, 2026

KurtCattiSchmidt added 8 commits August 24, 2026 15:47

Adding fetch, still rough

7895573

Clarifying the two sheets

1e2c6fe

Updating steps and fixing error

ce94175

Ordered set of unique tokens

bed9d4a

Adding note about FOUC in example

64288aa

Adding HTMLTemplateElement.shadowRootAdoptedStyleSheets, shadowrootse…

192cf8a

…rializable, and failed fetch behavior

Fixing specifier splitting by whitespace

ff7478e

Remove shadowrootadoptedstylesheets proposal

cbaba09

KurtCattiSchmidt force-pushed the sas-fetch branch from acba836 to cbaba09 Compare August 24, 2026 22:48

Wrapping long lones

a614d99

KurtCattiSchmidt requested review from emilio, jakearchibald and noamr August 25, 2026 14:52

noamr reviewed Aug 25, 2026

View reviewed changes

Addressing Noam's feedback, removing title + alternate split

79a4833

KurtCattiSchmidt added the agenda+ To be discussed at a triage meeting label Aug 26, 2026

KurtCattiSchmidt added 4 commits August 26, 2026 08:46

Removing redundant exception catching statement

eca6d16

Minor additional fixes

1e12ace

href -> import, removing type=module

780137e

Cleanups

5fdf497

emilio reviewed Aug 28, 2026

View reviewed changes

KurtCattiSchmidt removed the agenda+ To be discussed at a triage meeting label Aug 28, 2026

KurtCattiSchmidt closed this Aug 28, 2026

Uh oh!

Conversation

KurtCattiSchmidt commented Apr 6, 2026 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

noamr commented Apr 16, 2026

Uh oh!

This comment was marked as outdated.

noamr commented Apr 16, 2026

Uh oh!

KurtCattiSchmidt commented Apr 22, 2026

Uh oh!

emilio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yoavweiss commented Jul 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

noamr left a comment

Choose a reason for hiding this comment

Uh oh!

noamr Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

noamr Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

noamr Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

KurtCattiSchmidt Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

keithamus commented Aug 28, 2026

Uh oh!

emilio left a comment

Choose a reason for hiding this comment

Uh oh!

emilio Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

noamr commented Aug 28, 2026

Uh oh!

annevk commented Aug 28, 2026

Uh oh!

KurtCattiSchmidt commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KurtCattiSchmidt commented Aug 28, 2026

Uh oh!

annevk commented Aug 29, 2026

Uh oh!

noamr commented Aug 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

8 participants

KurtCattiSchmidt commented Apr 6, 2026 •

edited by pr-preview Bot

Loading

noamr Aug 25, 2026 •

edited

Loading

KurtCattiSchmidt commented Aug 28, 2026 •

edited

Loading

noamr commented Aug 29, 2026 •

edited

Loading