ShadyCSS provides a shim for, CSS Custom Properties, CSS Mixins with @apply
support,
and ShadowDOM V1 style encapsulation with the ShadyDOM library.
ShadyCSS requires support for CustomElements, ShadowDOM, MutationObserver, Promise, Object.assign
This library is distributed as ES2016 only, due to the included <custom-style>
element definition.
The shim will transparently no-op if some or all native support is available.
If native ShadowDOM is not available, stylesheet selectors will be modified to simulate scoping.
if CSS Custom Properties are not available, stylesheets will be generated with realized values for custom properties.
@apply
is not native in any browser, so they will be shimmed with CSS Custom Properties in browsers that support them, or via generated stylesheets with the CSS Custom Properties shim.
To use ShadyCSS:
-
First, call
ShadyCSS.prepareTemplate(template, name)
on a<template>
element that will be imported into ashadowRoot
. -
When the element instance is connected, call
ShadyCSS.applyStyle(element)
-
Create and stamp the element's shadowRoot
-
Whenever dynamic updates are required, call
ShadyCSS.applyStyle(element)
. -
If a styling change is made that may affect the whole document, call
ShadyCSS.updateStyles()
.
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>
ShadyCSS.prepareTemplate(myElementTemplate, 'my-element');
class MyElement extends HTMLElement {
connectedCallback() {
ShadyCSS.applyStyle(this);
if (!this.shadowRoot) {
this.attachShadow({mode: 'open'});
this.shadowRoot.appendChild(
document.importNode(myElementTemplate.content, true));
}
}
}
customElements.define('my-element', MyElement);
</script>
ShadyCSS can also be used with type extension elements by supplying the base
element name to prepareTemplate
as a third argument.
<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>
ShadyCSS.prepareTemplate(myElementTemplate, 'my-element', 'div');
class MyElement extends HTMLDivElement {
connectedCallback() {
ShadyCSS.applyStyle(this);
if (!this.shadowRoot) {
this.attachShadow({mode: 'open'});
this.shadowRoot.appendChild(
document.importNode(myElementTemplate.content, true));
}
}
}
customElements.define('my-element', MyElement, {extends: 'div'});
</script>
The <custom-style>
element allows <style>
elements that are not inside of
Custom Elements to be processed by the ShadyCSS library.
<custom-style>
<style>
html {
--content-color: brown;
}
</style>
</custom-style>
<my-element>This text will be brown!</my-element>
To set the value of a CSS Custom Property imperatively, ShadyCSS.applyStyle
and ShadyCSS.updateStyles
support an additional argument of an object mapping
variable name to value.
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>
let el = document.querySelector('my-element#a');
// Set the color of all my-element instances to 'green'
ShadyCSS.updateStyles({'--content-color' : 'green'});
// Set the color my-element#a's text to 'red'
ShadyCSS.applyStyle(el, {'--content-color' : 'red'});
</script>
You must have a selector to the left of the ::slotted
pseudo-element.
Dynamic changes are not automatically applied. If elements change such that they
conditionally match selectors they did not previously, ShadyCSS.updateStyles()
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 matcha selector that defines the property in its host's stylesheet.
If ShadyCss.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.
If there are only <custom-style>
elements in the page, you may call
ShadyCSS.updateStyles()
to remove the flash of unstyled content.
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.