Learn how to use CSS module scripts to import CSS stylesheets using the same syntax as JavaScript modules.

Dan Clark

With the new CSS module scripts feature, you can load CSS style sheets withimport statements,just likeJavaScriptmodules. The style sheetscan then be applied to documents orshadowroots in the same manner asconstructablestylesheets. This canbe more convenient andmoreperformantthan other ways of importing and applying CSS.

Browser Support

CSS module scripts are available by default in Chrome and Edge in version 93.

Support in Firefox and Safari is not yet available. Implementation progress can be tracked at theGecko bug andWebKitbug, respectively.

Prerequisites

• Familiarity withJavaScriptmodules.
• Familiarity withconstructablestylesheets.

Using CSS module scripts

Import a CSS module script and apply it to a document or a shadow root like this:

importsheetfrom'./styles.css'assert{type:'css'};document.adoptedStyleSheets=[sheet];shadowRoot.adoptedStyleSheets=[sheet];

The default export of a CSS module script is aconstructablestylesheet whosecontents are those of the imported file. Like any other constructable stylesheet, it is applied todocuments or shadow roots usingadoptedStyleSheets.

Unlike other ways of applying CSS from JavaScript, there is no need to create<style> elements ormess with JavaScript strings of CSS text.

CSS modules also have some of the same benefits as JavaScript modules.

• Deduplication: if the same CSS file is imported from multiple places in an application, it willstill only be fetched, instantiated, and parsed a single time.
• Consistent order of evaluation: when the importing JavaScript is running, it can rely on thestylesheet it imports having already been fetched and parsed.
• Security: modules are fetched withCORSand use strict MIME-type checking.

Import Assertions (what's with the 'assert'?)

Theassert { type: 'css' } part of theimport statement is animportassertion. This is required; without it, theimport istreated as a normal JavaScript module import, and will fail if the imported file has anon-JavaScript MIME type.

importsheetfrom'./styles.css';// Failed to load module script:// Expected a JavaScript module// script but the server responded// with a MIME type of "text/css".

Dynamically imported stylesheets

You can also import a CSS module usingdynamicimport, with a new second parameter for thetype:'css' import assertion:

constcssModule=awaitimport('./style.css',{assert:{type:'css'}});document.adoptedStyleSheets=[cssModule.default];

Currently CSS@import rules don't workin constructable stylesheets, including CSS module scripts. If@import rules are present in aconstructable stylesheet, those rules will be ignored.

/* atImported.css */div{background-color:blue;}

/* styles.css */@importurl('./atImported.css');/* Ignored in CSS module */div{border:1emsolidgreen;}

<!-- index.html --><script type="module">    import styles from './styles.css' assert { type: "css" };    document.adoptedStyleSheets = [styles];</script><div>This div will have a green border but no background color.</div>

Support for@import in CSS module scripts may be added to the specification. Track thisspecification discussion inthe GitHub issue.