@corpuscule/custom-builtin-elements
v0.3.0
Published
A full-featured polyfill for customized built-in elements
Downloads
16
Maintainers
Readme
@corpuscule/custom-builtin-elements
This package is a polyfill for the Customized Built-in Elements specification.
Rationale
Unfortunately, Safari is not going to support this part of the Custom Elements spec, as well as IE 11 and Edge do not have this feature on board. This polyfill aims to fill this gap and provide support for this feature for all browsers that miss it.
You may have a question: why choose this polyfill if there already is a
well-known and popular @ungap/custom-elements-builtin
?
Unfortunately, it has some problems that make it hard to use. For example, with
the @ungap/custom-elements-builtin
you cannot use class constructors or create new
elements with the new
operator.
This polyfill provides the solution for all of these issues and makes it possible to use the customized built-in elements in all browsers that lack support for them: Safari, Edge, IE 11.
Installation
npm:
$ npm install @corpuscule/custom-builtin-elements
Yarn:
$ yarn add @corpuscule/custom-builtin-elements
import 'https://unpkg.com/@corpuscule/custom-builtin-elements';
Support
To use this polyfill with IE 11 you need the following tools:
Symbol
polyfill (with support forSymbol.hasInstance
).Promise
polyfill.- @babel/plugin-transform-instanceof
applied to your code that uses
instanceof
against any built-in constructor (likeHTMLButtonElement
etc.).
Also, for all browsers that do not support native web components, you need an
implementation of the customElements
registry existing. You have the following
choices:
- Use
@webcomponents/webcomponentsjs
, that will also add support for autonomous custom elements. - Use the minimal implementation of
customElements
provided by this polyfill that would allow you to use the customized built-in elements only.
Note that both minimal implementation or @webcomponents/webcomponentsjs
polyfill should be executed before the main polyfill because it will
override methods of the customElements
registry.
Examples of adding minimal implementation:
- via npm and ESM:
import '@corpuscule/custom-builtin-elements/lib/customElementsBase';
import '@corpuscule/custom-builtin-elements';
- via https://unpkg.com and
script
:
<script src="https://unpkg.com/@corpuscule/custom-builtin-elements/lib/customElementsBase.js"></script>
<script src="https://unpkg.com/@corpuscule/custom-builtin-elements"></script>
Example
class ClickCounter extends HTMLButtonElement {
constructor() {
super();
this._count = 0;
this.increase = this.increase.bind(this);
}
get count() {
return this._count;
}
connectedCallback() {
this.addEventListener('click', this.increase);
}
disconnectedCallback() {
this.removeEventListener('click', this.increase);
}
increase() {
this._count += 1;
}
}
customElements.define('x-click-counter', ClickCounter, {extends: 'button'});