Custom Element Constructor


Facilitate the registration of LWC Constructor as Custom Elements.


As of today, the way to generate a qualifying Custom Element from a LWC Constructor, is via an experimental API: buildCustomElementConstructor(). Since this is a primary use case for LWC, we want to make it more ergonomic, and simpler. Additionally, the experimental API allow you to generate more than one Custom Element per LWC Constructors, which does not align with the web components semantics.


  1. Provide a dead simple way to register a custom element from a LWC Constructor.
  2. Preserve the web components semantics.


This proposal provides a high-level API (an abstraction layer) for authors to access the custom element associated to a LWC Constructor:

import XFoo from 'x/foo';
customElements.define('x-foo', XFoo.CustomElementConstructor);
// using tagName `x-foo`:



Semantics and Invariants

Implementation Details

LightningElement.CustomElementConstructor is a static getter that can be accessed by any Constructor extending LightningElement. This getter can rely on the this value, which points to the sub class. This can be used in a Map to link the LWC to the Custom Element. This is very similar to the trick we use in LightningContextElement.Provider for context.

As a consequence of this change, the existing experimental API can be deprecated.

Adoption strategy

This is a brand new feature, we just need to document it.

How we teach this