Social Media Photo by Joanna Kosinska on Unsplash
An unobtrusive customElements V1 polyfill.
This module is a ponyfill but the official module for CE is not here.
Use this module only if you understand what a ponyfill here, and only if you are capable of not invoking this more than once in your project.
The polyfill gracefully enhances the following minimum versions of at least these browsers, up to their latest version:
This polyfill provides both global fixes and ESM or CJS modules.
The index.js and its min.js versions are dedicated for usage within HTML pages.
<!-- simply include this script on top of your HTML files -->
<script src="//unpkg.com/@webreflection/custom-elements"></script>
Patches are applied after feature detections to bring customElements
V1 to legacy browsers, as well as modern browsers that are not fully specs compliant (i.e. Safari / WebKit).
The esm/index.js is the default export. The module does not patch anything until explicitly invoked.
import cePolyfill from '@webreflection/custom-elements';
const customElements = cePolyfill(self || window || global);
const {define, get, whenDefined} = customElements;
Everything said for ESM, except the file is in cjs/index.js.
const cePolyfill = require('@webreflection/custom-elements');
const customElements = cePolyfill(self || window || global);
const {define, get, whenDefined} = customElements;
If you’d like to not pollute the global object with all the patches, you need to pass an object that contains all needed globals.
However, this is strongly discouraged unless you are doing this to test/cover something via node.js only, not browsers.
Example
const customElements = cePolyfill({
// pass a bound version of customElements if available
customElements: self.customElements && {
// only define and get are needed
define: customElements.define.bind(customElements),
get: customElements.get.bind(customElements)
},
// needed globals through this `self` namespace
Map, MutationObserver, Object, Set, WeakMap,
HTMLElement, Error, TypeError,
// the `document.createElement` might be patched regardless
document,
// the `Element.prototype.attachShadow` might be patched regardless
Element,
// the `Node.prototype.isConnected` might be patched regardless
Node,
// one or more globals you'd like to ake available for builtin extends
HTMLButtonElement,
HTMLDivElement,
});
This is not a ShadowDOM polyfill, this is just the current Custom Elements V1 as specified by standard bodies.
If you are looking for a reasonable attempt to polyfill ShadowDOM too, ShadyDOM would be my recommendation.
Please note, once this polyfill has been tested enough it will be moved to under @ungap.
Please also note that: