Product
Introducing SSO
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
@webcomponents/shadycss
Advanced tools
Readme
ShadyCSS provides a library to simulate ShadowDOM style encapsulation (ScopingShim), a shim for the proposed CSS mixin @apply
syntax (ApplyShim), and a library to integrate document-level stylesheets with both of the former libraries (CustomStyleInterface).
ShadyCSS requires support for the <template>
element, ShadowDOM, MutationObserver, Promise, and Object.assign
ShadyCSS can be used by loading the ScopingShim, ApplyShim, CustomStyleInterface, or any combination of those.
The most-supported loading order is:
Import the @webcomponents/shadycss
module to interact with ShadyCSS. Note this
module does not load the polyfill, instead this module is used to interact
with ShadyCSS if the polyfill is loaded, and is safe to use whether or not
ShadyCSS is loaded.
There is also a legacy global API exposed on window.ShadyCSS
. Prefer use of
the @webcomponents/shadycss
module described above.
ShadyCSS = {
prepareTemplate(templateElement, elementName, elementExtension) {},
styleElement(element) {},
styleSubtree(element, overrideProperties) {},
styleDocument(overrideProperties) {},
getComputedStyleValue(element, propertyName) {},
nativeCss: Boolean,
nativeShadow: Boolean,
};
ScopingShim provides simulated ShadyDOM style encapsulation, and a shim for CSS Custom Properties.
ScopingShim works by rewriting style contents and transforming selectors to enforce scoping. Additionally, if CSS Custom Properties is not detected, ScopingShim will replace CSS Custom Property usage with realized values.
Here's an example of a custom element when Scoping Shim is not needed.
<my-element>
<!-- shadow-root -->
<style>
:host {
display: block;
}
#container slot::slotted(*) {
color: gray;
}
#foo {
color: black;
}
</style>
<div id="foo">Shadow</div>
<div id="container">
<slot>
<!-- span distributed here -->
</slot>
</div>
<!-- /shadow-root -->
<span>Light</span>
</my-element>
becomes:
<style scope="my-element">
my-element {
display: block;
}
my-element#container > * {
color: gray;
}
my-element#foo {
color: black;
}
</style>
<my-element>
<div id="foo">Shadow</div>
<div id="container">
<span>Light</span>
</div>
</my-element>
ApplyShim provides a shim for the @apply
syntax proposed at https://tabatkins.github.io/specs/css-apply-rule/, which expands the definition CSS Custom Properties to include objects that can be applied as a block.
This is done by transforming the block definition into a set of CSS Custom Properties, and replacing uses of @apply
with consumption of those custom properties.
The @apply
proposal has been abandoned in favor of the ::part/::theme Shadow Parts spec. Therefore, the ApplyShim library is deprecated and provided only for backwards compatibility. Support going forward will be limited to critical bug fixes.
Mixin properties cannot be modified at runtime.
Nested mixins are not supported.
Shorthand properties are not expanded and may conflict with more explicit properties. Whenever shorthand notations are used in conjunction with their expanded forms in @apply
, depending in the order of usage of the mixins, properties can be overridden. This means that using both background-color: green;
and background: red;
in two separate CSS selectors
can result in background-color: transparent
in the selector that background: red;
is specified.
#nonexistent {
--my-mixin: {
background: red;
}
}
with an element style definition of
:host {
display: block;
background-color: green;
@apply (--my-mixin);
}
results in the background being transparent
, as an empty background
definition replaces
the @apply
definition.
For this reason, we recommend avoiding shorthand properties.
Here we define a block called --mixin
at the document level, and apply that block to my-element
somewhere in the page.
html {
--mixin: {
border: 2px solid black;
background-color: green;
}
}
my-element {
border: 1px dotted orange;
@apply --mixin;
}
becomes:
html {
--mixin_-_border: 2px solid black;
--mixin_-_background-color: green;
}
my-element {
border: var(--mixin_-_border, 1px dotted orange);
background-color: var(--mixin_-_background-color);
}
CustomStyleInterface provides API to process <style>
elements that are not inside of
ShadowRoots, and simulate upper-boundary style scoping for ShadyDOM.
To add document-level styles to ShadyCSS, one can call CustomStyleInterface.addCustomStyle(styleElement)
or CustomStyleInterface.addCustomStyle({getStyle: () => styleElement})
An example usage of the document-level styling api can be found in examples/document-style-lib.js
, and another example that uses a custom element wrapper can be found in examples/custom-style-element.js
<style class="document-style">
html {
--content-color: brown;
}
</style>
<my-element>This text will be brown!</my-element>
<script>
CustomStyleInterface.addCustomStyle(
document.querySelector('style.document-style')
);
</script>
Another example with a wrapper <custom-style>
element
<custom-style>
<style>
html {
--content-color: brown;
}
</style>
</custom-style>
<script>
class CustomStyle extends HTMLElement {
constructor() {
CustomStyleInterface.addCustomStyle(this);
}
getStyle() {
return this.querySelector('style');
}
}
</script>
<my-element>This this text will be brown!</my-element>
Another example with a function that produces style elements
<my-element>This this text will be brown!</my-element>
<script>
CustomStyleInterface.addCustomStyle({
getStyle() {
const s = document.createElement('style');
s.textContent = 'html{ --content-color: brown }';
return s;
},
});
</script>
To use ShadyCSS:
Import the ShadyCSS interface module. (Note that this module does not load the polyfill itself, rather it provides functions for interfacing with ShadyCSS if it is loaded.)
import * as shadyCss from '@webcomponents/shadycss';
First, call shadyCss.prepareTemplate(template, name)
on a
<template>
element that will be imported into a shadowRoot
.
When the element instance is connected, call shadyCss.styleElement(element)
.
Create and stamp the element's shadowRoot.
Whenever dynamic updates are required, call shadyCss.styleSubtree(element)
.
If a styling change is made that may affect the whole document, call
shadyCss.styleSubtree(document.documentElement)
.
The following example uses ShadyCSS and ShadyDOM to define a custom element.
<template id="myElementTemplate">
<style>
:host {
display: block;
padding: 8px;
}
#content {
background-color: var(--content-color);
}
.slot-container ::slotted(*) {
border: 1px solid steelblue;
margin: 4px;
}
</style>
<div id="content">Content</div>
<div class="slot-container">
<slot></slot>
</div>
</template>
<script type="module">
import * as shadyCss from '@webcomponents/shadycss';
const myElementTemplate = document.body.querySelector('#myElementTemplate');
shadyCss.prepareTemplate(myElementTemplate, 'my-element');
class MyElement extends HTMLElement {
connectedCallback() {
shadyCSS.styleElement(this);
if (!this.shadowRoot) {
this.attachShadow({mode: 'open'});
this.shadowRoot.appendChild(
document.importNode(myElementTemplate.content, true)
);
}
}
}
customElements.define('my-element', MyElement);
</script>
To set the value of a CSS Custom Property imperatively, use the styleSubtree
function from the @webcomponents/shadycss
module. This function supports an
additional argument of an object mapping variable name to value, and works
whether or not ShadyCSS is loaded.
When using ApplyShim, defining new mixins or new values for current mixins imperatively is not supported.
<my-element id="a">Text</my-element>
<my-element>Text</my-element>
<script type="module">
import * as shadyCSS from '@webcomponents/shadycss';
const el = document.querySelector('my-element#a');
// Set the color of all my-element instances to 'green'
shadyCss.styleSubtree(document.documentElement, {'--content-color': 'green'});
// Set the color my-element#a's text to 'red'
shadyCss.styleSubtree(el, {'--content-color': 'red'});
</script>
You must have a selector for ascendants of the <slot>
element when using the ::slotted
pseudo-element.
You cannot use any selector for the <slot>
element. Rules like .foo .bar::slotted(*)
are not supported.
@apply
Dynamic changes are not automatically applied. If elements change such that they
conditionally match selectors they did not previously,
styleElement(document.documentElement)
must be called.
For a given element's shadowRoot, only 1 value is allowed per custom properties. Properties cannot change from parent to child as they can under native custom properties; they can only change when a shadowRoot boundary is crossed.
To receive a custom property, an element must directly match a selector that defines the property in its host's stylesheet.
<custom-style>
Flash of unstyled contentIf applyStyle
is never called, <custom-style>
elements will process after
HTML Imports have loaded, after the document loads, or after the next paint.
This means that there may be a flash of unstyled content on the first load.
<slot>
Crawling the DOM and updating styles is very expensive, and we found that trying to
update mixins through <slot>
insertion points to be too expensive to justify for both
polyfilled CSS Mixins and polyfilled CSS Custom Properties.
External stylesheets loaded via <link rel="stylesheet">
within a shadow root or
@import
syntax inside a shadow root's stylesheet are not currently shimmed by
the polyfill. This is mainly due to the fact that shimming them would require
a fetch of the stylesheet text that is async cannot be easily coordinated with
the upgrade timing of custom elements using them, making it impossible to avoid
"flash of unstyled content" when running on polyfill.
ShadyCSS mimics the behavior of shadow dom, but it is not able to prevent document
level styling to affect elements inside a shady dom. Global styles defined in
index.html
or any styles not processed by ShadyCSS will affect all elements on the page.
To scope document level styling, the style must be wrapped in the <custom-style>
element
found in Polymer, or use the CustomStyleInterface
library to modify document level styles.
ShadyCSS works by processing a template for a given custom element class. Only the style elements present in that template will be scoped for the custom element's ShadowRoot.
FAQs
Polyfill for Scoped CSS
The npm package @webcomponents/shadycss receives a total of 90,691 weekly downloads. As such, @webcomponents/shadycss popularity was classified as popular.
We found that @webcomponents/shadycss demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.