Custom Elements V1 Polyfill

^{Social Media Photo by Joanna Kosinska on Unsplash}

An unobtrusive customElements V1 polyfill.

Warning: @ungap/custom-elements is what you are looking for!

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.

- - -

Compatibility

The polyfill gracefully enhances the following minimum versions of at least these browsers, up to their latest version:

* Chrome 38
* Firefox 14
* Opera 25
* Internet Explorer 11 and Edge 12
* Safari 8 and WebKit based
* Samsung Internet 3

How To Polyfill

This polyfill provides both global fixes and ESM or CJS modules.

$3

The index.js and its min.js versions are dedicated for usage within _HTML_ pages.

``html


`

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).

$3

The esm/index.js is the default export. The module does not patch anything until explicitly invoked.

`js
import cePolyfill from '@webreflection/custom-elements';
const customElements = cePolyfill(self || window || global);
const {define, get, whenDefined} = customElements;
`

$3

Everything said for _ESM_, except the file is in cjs/index.js.

`js
const cePolyfill = require('@webreflection/custom-elements');
const customElements = cePolyfill(self || window || global);
const {define, get, whenDefined} = customElements;
`


#### Extra note about ESM/CJS modules

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
`js
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,
});
``

To Keep In Mind

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:

* to polyfill _customElements_ without builtin extends use custom-elements-no-builtin instead
* for even more legacy browsers, ditch this module and use document-register-element instead, but bear in mind this older version has its own legacy caveats