Security News
PyPI Introduces Digital Attestations to Strengthen Python Package Security
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
@webcomponents/webcomponentsjs
Advanced tools
@webcomponents/webcomponentsjs is a polyfill library that enables the use of Web Components in browsers that do not natively support them. It provides polyfills for Custom Elements, Shadow DOM, HTML Imports, and Template, allowing developers to use these modern web standards across all browsers.
Custom Elements
This feature allows you to define custom HTML elements. The code sample demonstrates creating a custom element called 'my-element' with a shadow DOM containing a paragraph.
class MyElement extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.innerHTML = '<p>Hello, World!</p>';
}
}
customElements.define('my-element', MyElement);
Shadow DOM
This feature allows you to encapsulate styles and markup within a custom element. The code sample demonstrates creating a custom element with a shadow DOM that styles a paragraph.
class MyShadowElement extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.innerHTML = '<style>p { color: red; }</style><p>Shadow DOM Content</p>';
}
}
customElements.define('my-shadow-element', MyShadowElement);
HTML Imports
This feature allows you to include HTML documents in other HTML documents. The code sample demonstrates importing an HTML file that contains a custom element.
import './my-component.html';
// Assuming my-component.html contains:
// <link rel="import" href="./my-element.html">
// <my-element></my-element>
HTML Template
This feature allows you to define HTML templates that can be reused. The code sample demonstrates creating a template with styles and content, and then appending it to the document body.
const template = document.createElement('template');
template.innerHTML = '<style>p { color: blue; }</style><p>Template Content</p>';
document.body.appendChild(template.content.cloneNode(true));
Lit is a library for building fast, lightweight web components. It offers a more modern and efficient approach compared to @webcomponents/webcomponentsjs, with features like reactive properties and declarative templates.
Stencil is a compiler that generates Web Components and builds high-performance web apps. It provides a more comprehensive solution with TypeScript support, JSX, and a focus on performance and developer experience.
Hybrids is a UI library for creating Web Components with simple and functional API. It emphasizes simplicity and functional programming principles, offering a different approach compared to the polyfill-focused @webcomponents/webcomponentsjs.
Note. For polyfills that work with the older Custom Elements and Shadow DOM v0 specs, see the v0 branch.
Note. For polyfills that include HTML Imports, see the v1 branch.
A suite of polyfills supporting the Web Components specs:
For browsers that need it, there are also some minor polyfills included:
HTMLTemplateElement
Promise
Event
, CustomEvent
, MouseEvent
constructors and Object.assign
, Array.from
(see webcomponents-platform)URL constructor
npm install @webcomponents/webcomponentsjs
You can also load the code from a CDN such as unpkg: https://unpkg.com/@webcomponents/webcomponentsjs@2.0.0/
webcomponents-bundle.js
The webcomponents-bundle.js
contains all of the web components polyfills and is
suitable for use on any supported browser. All of the polyfill code will be loaded
but each polyfill will only be used based on feature detection.
The bundle includes Custom Elements, Shady DOM/CSS and generic platform polyfills
(such as ES6 Promise, Constructable events, etc.) (needed by Internet Explorer 11),
and Template (needed by IE 11 and Edge).
The webcomponents-bundle.js
is very simple to use but it does load code
that is not needed on most modern browsers, slowing page load. For best performance,
use the webcomponents-loader.js
.
Here's an example:
<!-- load webcomponents bundle, which includes all the necessary polyfills -->
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
<!-- load the element -->
<script type="module" src="my-element.js"></script>
<!-- use the element -->
<my-element></my-element>
webcomponents-loader.js
The webcomponents-loader.js
is a client-side loader that dynamically loads the
minimum polyfill bundle, using feature detection.
webcomponents-loader.js
can be loaded synchronously, or asynchronously depending on your needs.
If you have inlined the source of webcomponent-loader.js
, then you should specify window.WebComponents.root
as the root from which to load the polyfills.
For example:
<script>
window.WebComponents = window.WebComponents || {};
window.WebComponents.root = 'node_modules/@webcomponents/webcomponentsjs/';
</script>
When loaded synchronously, webcomponents-loader.js
behaves similarly to webcomponents-bundle.js
.
The appropriate bundle will be loaded with document.write()
to ensure that WebComponent polyfills are available for subsequent scripts and modules.
Here's an example:
<!-- load the webcomponents loader, which injects the necessary polyfill bundle -->
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
<!-- load the element -->
<script type="module" src="my-element.js"></script>
<!-- use the element -->
<my-element></my-element>
When loaded asychronously with the defer
attribute, polyfill bundles will be loaded asynchronously,
which means that scripts and modules that depend on webcomponents APIs must be loaded
using WebComponents.waitFor
function.
The WebComponents.waitFor
function takes a callback function as an argument, and will evaluate that callback after the polyfill bundle has been loaded.
The callback function should load scripts that need the polyfills (typically via import('my-script.js')
) and
should return a promise that resolves when all scripts have loaded.
Here's an example:
<!-- Load polyfills; note that "loader" will load these async -->
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js" defer></script>
<!-- Load a custom element definitions in `waitFor` and return a promise -->
<script type="module">
WebComponents.waitFor(() => {
// At this point we are guaranteed that all required polyfills have
// loaded, and can use web components API's.
// The standard pattern is to load element definitions that call
// `customElements.define` here.
// Note: returning the import's promise causes the custom elements
// polyfill to wait until all definitions are loaded and then upgrade
// the document in one batch, for better performance.
return import('my-element.js');
});
</script>
<!-- Use the custom element -->
<my-element></my-element>
The WebComponents.waitFor
function may be called multiple times, and the callback functions will be processed in order.
Here's a more complicated example:
<!-- Load polyfills; note that "loader" will load these async -->
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js" defer></script>
<script type="module">
WebComponents.waitFor(async () => {
if (!window.fetch) {
await import('node_modules/fetch-polyfill/fetch.js');
}
return import('my-element.js');
})
</script>
<script type="module">
</script>
The WebComponentsReady
event is fired when polyfills and user scripts have loaded and custom elements have been upgraded. This event is generally not needed; however, it may be useful in some cases like testing. If imperative code should wait until a specific custom element definition has loaded, it can use the platform customElements.whenDefined
API.
custom-elements-es5-adapter.js
According to the spec, only ES6 classes (https://html.spec.whatwg.org/multipage/scripting.html#custom-element-conformance) may be passed to the native customElements.define
API. For best performnace, ES6 should be served to browsers that support it, and ES5 code should be serve to those that don't. Since this may not always be possible, it may make sense to compile and serve ES5 to all browsers. However, if you do so, ES5-style custom element classes will now not work on browsers with native Custom Elements because ES5-style classes cannot properly extend ES6 classes, like HTMLElement
.
As a workaround, if your project has been compiled to ES5, load custom-elements-es5-adapter.js
before defining Custom Elements. This adapter will automatically wrap ES5.
The adapter must NOT be compiled.
The polyfills are intended to work in the latest versions of evergreen browsers. See below for our complete browser support matrix:
Polyfill | Edge | IE11+ | Chrome* | Firefox* | Safari 9+* | Chrome Android* | Mobile Safari* |
---|---|---|---|---|---|---|---|
Custom Elements | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Shady CSS/DOM | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
*Indicates the current version of the browser
The polyfills may work in older browsers, however require additional polyfills (such as classList, or other platform polyfills) to be used. We cannot guarantee support for browsers outside of our compatibility matrix.
If you wish to build the bundles yourself, you'll need node
and npm
on your system:
npm
to install gulp.js: npm install -g gulp
Now you are ready to build the polyfills with:
# install dependencies
npm install
# build
npm run build
The builds will be placed into the root directory.
See the contributing guide
Everything in this repository is BSD style license unless otherwise specified.
Copyright (c) 2015 The Polymer Authors. All rights reserved.
webcomponents-loader.js
with the defer
attribute, scripts that rely on the polyfills must be loaded using WebComponents.waitFor(loadCallback)
.The ShadowDOM polyfill is not able to encapsulate CSS in ShadowDOM out of the box. You need to use specific code from the ShadyCSS library, included with the polyfill. See ShadyCSS instructions.
See #215 for background.
In Edge and IE, instances of Custom Elements have a constructor
property of HTMLUnknownElementConstructor
and HTMLUnknownElement
, respectively. It's unsafe to rely on this property for checking element types.
It's worth noting that customElement.__proto__.__proto__.constructor
is HTMLElementPrototype
and that the prototype chain isn't modified by the polyfills(onto ElementPrototype
, etc.)
Using the MutationObserver polyfill, it isn't possible to monitor mutations of an element marked contenteditable
.
See the mailing list
ShadyCSS :host()
rules can only have (at most) 1-level of nested parentheses in its argument selector under ShadyCSS. For example, :host(.zot)
and :host(.zot:not(.bar))
both work, but :host(.zot:not(.bar:nth-child(2)))
does not.
FAQs
Web Components Polyfills
We found that @webcomponents/webcomponentsjs demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 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.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.