Nonchalant Programming Master
Miss any of our Open RFC calls?Watch the recordings here! »


0.6.3 • Public • Published

Custom Elements with Builtin Extends

Build Status Greenkeeper badge WebReflection status


Please help me out testing the future version of this polyfill, as example by simply using @webreflection instead of @ungap in case you are getting this polyfill from some CDN.

New 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

Thanks in advance for making Custom Elements with Builtin Extends available to everyone ♥

Brings builtin extends to browsers that already have customElements (i.e. Safari).

See document-register-element to polyfill upfront all other legacy browsers too.

Please don't file any bug until you've read the Constructor Caveat section, and be sure you use features detection to bring in this polyfill only where needed.

  class MyButton extends HTMLButtonElement {
    static get observedAttributes() { return ['color']; }
    attributeChangedCallback(name, oldValue, newValue, nsValue) { = newValue;
    connectedCallback() {
      this.addEventListener('click', this);
    disconnectedCallback() {
      this.removeEventListener('click', this);
    handleEvent(event) {
      const next = this.nextElementSibling ||
      next.textContent = `${event.type} @ ${new Date}`;
  {'extends': 'button'}

Live ES2015 test

Live ES5 test

All Possible Features Detections

This is all it takes to have all the right polyfills in place.

if (this.customElements) {
  try {
    // feature detect browsers that "forgot" 🙄 to implement built-in extends
    customElements.define('built-in', document.createElement('p').constructor, {'extends':'p'});
  } catch(_) {
    // only WebKit or Safari
    document.write('<script src="//"><\x2fscript>');
} else {
  // only legacy browsers
  document.write('<script src="//"><\x2fscript>');
// everything else that needs a reliable customElements global
// with built-in extends capabilities
// Note: it's important it's one <script> tag after the previous one!

The, still readable, but minified version is here:

  catch(s){document.write('<script src="//"><\x2fscript>')}
  document.write('<script src="//"><\x2fscript>');

If for some reason your server / header has issues in sending <script> content:


Constructor Caveat

You cannot use the constructor in any meaningful way if you want to ensure API consistency, including setting properties, which means you cannot also use prop = value within the class declaration, as it's not possible to reflect those, same as it's not possible to use a constructor.

Create new elements via document.createElement('button', {is: 'my-button'}) but do not use new MyButton or incompatible browsers will throw right away because they made HTMLButtonElement and all others not usable as classes.

If you'd like to use instead of new CustomElement(), have a look at the custom-elements-new utility.

If you need a reliable entry point to setup your custom builtins use the connectedCallback method instead of the constructor so you're also sure all attributes are eventually already known and you'll have full control.

Alternatively, use a WeakSet to optionally invoke a setup.

const initialized = new WeakSet;
const setup = node => {
  initialized.add(node); = true;
class MyButton extends HTMLButtonElement {
  connectedCallback() {
    if (!initialized.has(this))
    // anything else

You can do the same at the beginning of attributeChangedCallback.

Compatible with ...

Any engine that supports genuine ES2015 syntax and the following features:

  • global MutationObserver, customElements, and Promise
  • assign, create, defineProperties, and setPrototypeOf from the Object


npm i @ungap/custom-elements-builtin

DownloadsWeekly Downloads






Unpacked Size

38.9 kB

Total Files


Last publish


  • avatar