@glowingblue-dev/shadow-css

Injects custom CSS into open shadow roots via HTML attributes with optional runtime watching for attribute changes or newly added nodes.

Features

• Add inline CSS or external .css files into open shadow roots
• Works with one or multiple attributes
• Optional live watching via MutationObserver: React to attribute changes and dynamically added nodes
• Zero dependencies, tiny footprint

Install

npm install @glowingblue-dev/shadow-css

or

yarn add @glowingblue-dev/shadow-css

Usage

Assuming an unstyleable third party WebComponent with an open shadow DOM like:

<custom-element>[#shadowDOM]<divclass="classname"></div>[/#shadowDOM]</custom-element>

Inline styles

<custom-elementdata-css=".classname { color: red; }"></custom-element>

import$shadowCSSfrom"@glowingblue-dev/shadow-css";$shadowCSS("data-css");

External stylesheet

<custom-elementdata-css="/path/to/styles.css"></custom-element>

$shadowCSS("data-css",{watch: true});

Multiple attributes

<custom-elementdata-theme="/themes/dark.css"
data-css=".classname { color: red; }"
></custom-element>

$shadowCSS(["data-theme","data-css"],{watch: true});

API

$shadowCSS(attrs?: string|string[],options?: {watch?: boolean},target?: Node): MutationObserver

• attrs — one or more attribute names (default: "data-css").
• options.watch — if true, sets up a MutationObserver to update when the attribute value changes or when new elements with the attribute are added.
• options.target - The target node to to look for attributes and optionally observe, defaults to the global document.

Always returns a MutationObserver instance, if watch: true it is already activated and observing the DOM and can be disabled by calling .disconnect() at any later point. If watch: false (default) you can activate it at a point of your choosing by calling .observe(<target>, <options>). The default options are attached to the returned MutationObserver instance for convenience.

Scoping tips

When using a shared stylesheet across multiple components, scope your rules with :host(...):

:host(custom-element) .selector {
transform:rotate(180deg);
}
:host(custom-element) {
& .selector {
...;
}
&:hover .selector {
...;
}
}

Limitations

• Only works with open shadow DOMs. Closed roots cannot be styled this way.
• Runs in browsers (relies on document).

License

MIT © Glowing Blue AG

Credits

Originally authored by exside