This polyfill has served the Web well in the last 6 years, but it's time to use the V1 only polyfill, which includes custom elements builtin extends like this one did before.
Such polyfill is in npm as @ungap/custom-elements and it does all features detections for every browser without any need to worry about anything.
<script src="//unpkg.com/@ungap/custom-elements"></script>
<script>
// alternatively, if bundlers are around
import '@ungap/custom-elements';
// or
require('@ungap/custom-elements');
</script>However, if all you need is custom elements without builtin extends, a module also used by @ungap/custom-elements , @webreflection/custom-elements-no-builtin is your stop.
<script>
if(!self.customElements)
document.write('<script src="//unpkg.com/@webreflection/custom-elements-no-builtin"><\x2fscript>');
</script>Alternatively, if it's a ponyfill hat you are after, see @webreflection/custom-elements instructions, as this module is already exported as ponyfill.
Please use the modern version of this polyfill instead, which includes the following features:
- no constructor caveats, everything works like in Chrome or Firefox
- better performance, only defined builtin gets observed, thanks to qsa-observer
- better memory handling: no leaks, and less operations
- better ShadowDOM integration: builtin extends are observed within ShadowDOM nodes, either opened or closed
A stand-alone lightweight version of Custom Elements V1 based on top, and compatible with, the battle-tested Custom Elements V0, already used in production with projects such as Google AMP HTML ⚡ and others.
Projects based on this polyfill should consider migrating to V1 API, which is natively available for Safari, Chrome, Firefox, and soon Edge too.
Where built in extends are not possible, you can use my latest built-in-element polyfill instead, which will leave natively working implementations untouched, and will apply the minimal amount of patches to native V1 without built-in elements (only Safari to date).
This is a bullet-proof way to bring in Custom Elements V1 when needed.
<script>this.customElements||document.write('<script src="//unpkg.com/document-register-element"><\x2fscript>');</script>
<script src="//unpkg.com/@ungap/custom-elements-builtin"></script>Don't worry though, only very old browsers will pass through that document.write, preserving its 20yo tested nature, while no modern browser will ever complain.
Stick above sequence of scripts on top of any of your pages, and you'll see that only very old browsers will download this polyfill, while others will load less than 1k, delivering Custom Elements with 100% native performance.
If you are bundling instead all the code, consider decoupling DRE bundling a part, or perform the same customElements check on the window and bring in only the right polyfill.
This polyfill, as well as built-in-element one, are about Custom Elements that are a specification a part.
If you need for some reason Shadow DOM, I suggest you to look at attach-shadow "poorlyfill", which provides most basic/needed mechanism to create sandboxed components.
You can try other polyfills around the web too but, if I were you, I'll stay away from Shadow DOM where it's not natively supported because other polyfills are heavier, less compatible, and yet not 100% reliable.
The version 1.9 of this polyfill does not patch browsers with full native support for Custom Elements, as anyone would expect from a polyfill based on features detection.
However, if your transpiler transforms native ES2015 classes into something incompatible, like TypeScript does in this case, you need to update, change, or better configure your tools to support proper classes.
Babel 7 should've solved this in core, so use Babel 7 if you need transpilers.
Since version 1.6 the ponyfill flag can be either a string,
representing the ponyfill type such "auto" or "force",
or an object, with the following shape:
installCE(global, {
type: 'force' || 'auto' (default),
noBuiltIn: true (default undefined / false)
});If you set noBuiltIn to true,
the V1 API will be polyfilled where needed.
No extra checks and patches will be applied to make custom elements built-in work.
As discussed in issue #86 there is currently no way to require document-register-element polyfill without automatic feature detection and possible global context pollution.
Since there could be some very specific case when the browser
should be force-patched, the pony version of the module
will not attempt to feature detect anything and it will only
enrich the environment once invoked.
const installCE = require('document-register-element/pony');
// by default, the second argument is 'auto'
// but it could be also 'force'
// which ignores feature detection and force
// the polyfill version of CustomElements
installCE(global, 'force');The ability to extend by simply defining classes:
// create a class with custom methods
// overrides, special behavior
class MyGreetings extends HTMLElement {
show() {
alert(this.textContent);
}
}
// define it in the CustomElementRegistry
customElements.define('my-greetings', MyGreetings);It is also possible to extend native components, as written in specs.
// extends some different native constructor
class MyButton extends HTMLButtonElement {}
// define it specifying what's extending
customElements.define('my-button', MyButton, {extends: 'button'});
// <button is="my-button">click me</button>
document.body.appendChild(
new MyButton
).textContent = 'click me';Special methods are also slightly different from v0:
- the
constructoris invoked instead of thecreatedCallbackone connectedCallbackis the newattachedCallbackdisconnectedCallbackis the newdetachedCallbackattributeChangedCallbackis sensitive to the public static list of attributes to be notified about
class MyDom extends HTMLElement {
static get observedAttributes() {
return ['country'];
}
attributeChangedCallback(name, oldValue, newValue) {
// react to changes for name
alert(name + ':' + newValue);
}
}
customElements.define('my-dom', MyDom);
var md = new MyDom();
md.setAttribute('test', 'nope');
md.setAttribute('country', 'UK'); // country: UKThe current standard cannot possibly be polifilled "1:1" with vanilla JavaScript because procedurally created instances need an upgrade.
If the constructor is needed to setup nodes, there are two solutions:
class MyElement extends HTMLElement {
// the self argument might be provided or not
// in both cases, the mandatory `super()` call
// will return the right context/instance to use
// and eventually return
constructor(...args) {
const self = super(...args);
self.addEventListener('click', console.log);
// important in case you create instances procedurally:
// var me = new MyElement();
return self;
}
}// base class to extend, same trick as before
class HTMLCustomElement extends HTMLElement {
constructor(...$) { const _ = super(...$); _.init(); return _; }
init() { /* override as you like */ }
}
// create any other class inheriting HTMLCustomElement
class MyElement extends HTMLCustomElement {
init() {
// just use `this` as regular
this.addEventListener('click', console.log);
// no need to return it
}
}Please keep in mind old gotchas with innerHTML or other caveats are still valid.
npm install document-register-element will put build/document-register-element.js inside node_modules/document-register-element/ of your project.
If you're working with a tool like Browserify, Webpack, RequireJS, etc, you can import the script at some point before you need to use the API.
import 'document-register-element' // ES2015
// or
require('document-register-element') // CommonJS
// or
define(['document-register-element'], function() {}) // AMDIf you're not using a module system, just place
node_modules/document-register-element/build/document-register-element.js
somewhere where it will be served by your server, then put
<script src="/path/to/document-register-element.js"></script>in your head element and you should be good to go.
Many thanks to cdnjs for hosting this script. Following an example on how to include it.
<script
src="//cdnjs.cloudflare.com/ajax/libs/document-register-element/1.13.0/document-register-element.js"
>/* W3C Custom Elements */</script>The live test page is here, containing all tests as listed in the test file.
The following list of desktop browsers has been successfully tested:
- Chrome
- Firefox
- IE 8 or greater (please read about IE8 caveats)
- Safari
- Opera
The following list of mobile OS has been successfully tested:
- iOS 5.1 or greater
- Android 2.2 or greater
- FirefoxOS 1.1 or greater
- KindleFire 3 or greater
- Windows Phone 7 or greater
- Opera Mobile 12 or greater
- Blackberry OS 7* and OS 10
- webOS 2 or LG TV
- Samsung Bada OS 2 or greater
- NOKIA Asha with Express Browser
The good old BB OS 7 is the only one failing the test with className which is not notified as attributeChanged when it's changed. This means BB OS 7 will also fail with id, however changing id at runtime has never been a common or useful pattern.
If you see the first clock ticking, the TL;DR answer is yes.
A basic HTML example page
<!DOCTYPE html>
<html>
<head>
<title>testing my-element</title>
<script src="js/document-register-element.js"></script>
<script src="js/my-element.js"></script>
</head>
<body>
<my-element>
some content
</my-element>
</body>with the following my-element.js content
var MyElement = document.registerElement(
'my-element',
{
prototype: Object.create(
HTMLElement.prototype, {
createdCallback: {value: function() {
console.log('here I am ^_^ ');
console.log('with content: ', this.textContent);
}},
attachedCallback: {value: function() {
console.log('live on DOM ;-) ');
}},
detachedCallback: {value: function() {
console.log('leaving the DOM :-( )');
}},
attributeChangedCallback: {value: function(
name, previousValue, value
) {
if (previousValue == null) {
console.log(
'got a new attribute ', name,
' with value ', value
);
} else if (value == null) {
console.log(
'somebody removed ', name,
' its value was ', previousValue
);
} else {
console.log(
name,
' changed from ', previousValue,
' to ', value
);
}
}}
})
}
);I wrote a couple of blog posts about this polyfill, and here's the quick summary:
- document-register-element.js is a stand alone polyfill which aims to support as many browsers as possible, without requiring extra dependencies at all, all in about 5KB minified and gzipped.
Add if you want the dom4 normalizer, and you'll find yourself in a modern DOM environment that works reliably with today's browsers, with an eye always open on performance.
Here a list of gotchas you might encounter when developing CustomElement components.
As described in issue 6 it's not possible to fully inherit a table, input, select, or other special element behaviors.
// This will NOT work as expected
document.registerElement(
'my-input',
{
prototype: Object.create(
HTMLInputElement.prototype
)
}
);
var mi = document.createElement('my-input');The correct way to properly implement a custom input that will be also backward compatible is the following one:
// This will NOT work as expected
document.registerElement(
'my-input',
{
extends: 'input', // <== IMPORTANT
prototype: Object.create(
HTMLInputElement.prototype
)
}
);
// how to create the input
var mi = document.createElement(
'input', // the extend
'my-input' // the enriched custom definition
);Another approach is to use just a basic HTMLElement component and initialize its content at runtime.
document.registerElement(
'my-input',
{
prototype: Object.create(
HTMLElement.prototype,
{
createdCallback: {value: function () {
// here the input
this.el = this.appendChild(
document.createElement('input')
);
}}
}
)
}
);
var mi = document.createElement('my-input');In this case every method that wants to interact with the input will refer this.el instead of just this.
In order to avoid huge performance impact, native behavior overwrite problems and incompatibilities, there is now a helper script,
which aim is to make off-line custom elements creation possible using template strings instead of needing manual document.createElement replacements.
The helper is a simple innerHTML function that returns the given node, after setting innerHTML and, in case the polyfill is used, initialize nodes.
This helper is needed in order to be aligned with native implementations, but please remember that createdCallback could be asynchronous, even if triggered ASAP after injecting HTML through this function.
If you change the style property via node.style.cssText or node.style.backgroundColor = "red" this change will most likely reflect through node.getAttribute("style").
In order to prevent footguns inside attributeChangedCallback invocations causing potential stack overflows, the style property has been filtered starting from version 0.1.1, also reflecting current native implementation where changing this special property won't invoke the callback.
(yes, even using node.setAttribute("style", "value") that you shouldn't ... just use node.style.cssText = "value" instead)
Starting from version 0.2.0 there is an experimental support for IE8.
There is a specific file that needs to be loaded in IE8 only upfront, plus a sequence of polyfills
that will be simply ignored by every browser but downloaded in IE8.
Please check base.html file in order to have a basic model to reuse in case you want to support IE8.
All tests pass and there is a map component example that already works in IE8 too.
Remember there are few things to consider when IE8 is a target but since it didn't cost many bytes to have it in, I've decided to merge the logic and maintain only one file that will work in IE8 too.
- it's IE8
- all operations are batched and eventually executed ASAP but asynchronously. This behavior is closer to native Mutation Observers but might have some extra glitch in rendering time
classNameis right now the only special attribute that reacts. Others might be implemented in the dre-ie8-upfront-fix.js file.- in order to have node reacting to attributes changes, these must be live on the DOM
- if you are using
extendswhen create a custom element, remember to minify the production code or wrap such reserved word in quotes
This project exists thanks to all the people who contribute. [Contribute].
Thank you to all our backers! 🙏 [Become a backer]
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]
