Requirements for custom element constructors

When authoring custom element constructors, authors are bound by the following conformance requirements:

• A parameter-less call to super() must be the first statement in the constructor body, to establish the correct prototype chain and this value before any further code is run.
• A return statement must not appear anywhere inside the constructor body, unless it is a simple early-return (return or return this).
• The element's attributes and children must not be inspected, as in the non-upgrade case none will be present, and relying on upgrades makes the element less usable.
• The element must not gain any attributes or children, as this violates the expectations of consumers who use the createElement or createElementNS methods.
• In general, work should be deferred to connectedCallback as much as possible—especially work involving fetching resources or rendering. However, note that connectedCallback can be called more than once, so any initialization work that is truly one-time will need a guard to prevent it from running twice.
• In general, the constructor should be used to set up initial state and default values, and to set up event listeners.

Several of these requirements are checked during element creation, either directly or indirectly, and failing to follow them will result in a custom element that cannot be instantiated by the parser or DOM APIs.

Core concepts

A custom element is an element that is custom. Informally, this means that its constructor and prototype are defined by the author, instead of by the user agent. This author-supplied constructor function is called the custom element constructor.

Two distinct types of custom elements can be defined:

1. A custom tag, which is defined with no extends option. These types of custom elements have local name equal to their defined name.
2. A type extension, which is defined with an extends option. These types of custom elements have local name equal to the value passed in their extends option, and their defined name is used as the value of the is attribute.

After a custom element is created, changing the value of the is attribute does not change the element's behavior.

Custom tags have the following element definition:

Categories:

Flow content.

Phrasing content.

Palpable content.

Contexts in which custom elements can be used:

Where phrasing content is expected.

Content model:

Transparent.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

Any attributes relevant to the element's functioning, as defined by the author

DOM interface:

Supplied by the author (inherits from HTMLElement).

A custom tag does not have any special meaning: it represents its children. A type extension inherits the semantics of the element that it extends.

A valid custom element name is a sequence of characters name that meets all of the following requirements:

• name must match the PotentialCustomElementName production:

  PotentialCustomElementName ::=

  [a-z] (PCENChar)* '-' (PCENChar)*

  PCENChar ::=

  "-" | "." | [0-9] | "_" | [a-z] | #xB7 | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x2FF] | [#x300-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x203F-#x2040] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]

  This uses the EBNF notation from the XML specification. [[!XML]]

• name must not be any of the following:

  • annotation-xml
  • color-profile
  • font-face
  • font-face-src
  • font-face-uri
  • font-face-format
  • font-face-name
  • missing-glyph

  The list of names above is the summary of all hyphen-containing element names from the applicable specifications, namely SVG and MathML. [[SVG11]] [[MathML]]

A custom element definition describes a custom element and consists of:

• a name, which is a valid custom element name;
• a local name, which is a local name;
• a constructor, which is a custom element constructor;
• a prototype, which is a JavaScript object;
• a list of observed attributes, which is a sequence<DOMString>;
• a collection of lifecycle callbacks, which is a map (described below);
• a construction stack, which is a list (initially empty).

Each custom element definition's construction stack is manipulated by the upgrade an element algorithm and the HTMLElement constructor. Each entry in the list will be either an element or an already constructed marker.

Each custom element definition's lifecycle callbacks is a map, whose three keys are the strings "connectedCallback", "disconnectedCallback", and "attributeChangedCallback". The corresponding values are either a JavaScript function object, or undefined. By default the value of each entry is undefined.

To look up a custom element definition, given a document, namespace, localName, and is, perform the following steps. They will return either a custom element definition or null:

1. If namespace is not the HTML namespace, return null.
2. If document does not have a browsing context, return null.
3. Let registry be document's associated Window's CustomElementsRegistry object.
4. If there is custom element definition in registry with name and local name both equal to localName, return that custom element definition.
5. If there is a custom element definition in registry with name equal to is and local name equal to localName, return that custom element definition.
6. Return null.

The CustomElementsRegistry interface

Each Window object is associated with a unique instance of a CustomElementsRegistry object, allocated when the Window object is created.

Custom element registries are associated with Window objects, instead of Document objects, since each custom element constructor inherits from the HTMLElement interface, and there is exactly one HTMLElement interface per Window object.

The customElements attribute of the Window interface must return the CustomElementsRegistry object for that Window object.

interface CustomElementsRegistry {
  void define(DOMString name, Function constructor, optional ElementRegistrationOptions options);
};

dictionary ElementRegistrationOptions {
  DOMString extends;
};

Every CustomElementsRegistry has a set of custom element definitions, initially empty. In general, algorithms in this specification look up elements in the registry by any of name, local name, or constructor.

A CustomElementsRegistry's list of defined local names is the list containing all of the local names of the custom element definitions in the registry.

Element definition is a process of adding a custom element definition to the CustomElementsRegistry. This is accomplished by the define method. When invoked, the define(name, constructor, options) method must run these steps:

1. If IsConstructor(constructor) is false, throw a TypeError and abort these steps.
2. If name is not a valid custom element name, throw a SyntaxError and abort these steps.
3. If this CustomElementsRegistry contains an entry with name name, throw a NotSupportedError and abort these steps.
4. If this CustomElementsRegistry contains an entry with constructor constructor, throw a NotSupportedError and abort these steps.
5. Let localName be name.
6. Let extends be the value of the extends member of options, or null if no such member exists.

7. If extends is not null:

   1. If extends is a valid custom element name, or if the element interface for extends and the HTML namespace is HTMLUnknownElement, throw a NotSupportedError and abort these steps.
   2. Set localName to extends.
8. Let observedAttributesIterable be Get(constructor, "observedAttributes"). Rethrow any exceptions.
9. If observedAttributesIterable is undefined, let observedAttributes be an empty sequence<DOMString>. Otherwise, let observedAttributes be the result of converting observedAttributesIterable to a sequence<DOMString>. Rethrow any exceptions.
10. Let prototype be Get(constructor, "prototype"). Rethrow any exceptions.
11. If Type(prototype) is not Object, throw a TypeError exception.
12. Let connectedCallback be Get(prototype, "connectedCallback"). Rethrow any exceptions.
13. If connectedCallback is not undefined, and IsCallable(connectedCallback) is false, throw a TypeError exception.
14. Let disconnectedCallback be Get(prototype, "disconnectedCallback"). Rethrow any exceptions.
15. If disconnectedCallback is not undefined, and IsCallable(disconnectedCallback) is false, throw a TypeError exception.
16. Let attributeChangedCallback be Get(prototype, "attributeChangedCallback"). Rethrow any exceptions.
17. If attributeChangedCallback is not undefined, and IsCallable(attributeChangedCallback) is false, throw a TypeError exception.
18. Let definition be a new custom element definition with name name, local name localName, constructor constructor, prototype prototype, observed attributes observedAttributes, and lifecycle callbacks connectedCallback, disconnectedCallback, and attributeChangedCallback (stored by their corresponding name).
19. Add definition to this CustomElementsRegistry.

Upgrades

To upgrade an element, given as input a custom element definition definition and an element element, run the following steps:

1. Add element to the end of definition's construction stack.
2. Let C be definition's constructor.
3. Let constructResult be Construct(C).
4. Remove element from the end of definition's construction stack.
5. If constructResult is an abrupt completion, return constructResult (i.e., re-throw the exception).

6. If SameValue(constructResult.[[\value]], element) is false, throw a InvalidStateError and terminate these steps.

   This can occur if C constructs another instance of the same custom element before calling super(), or if C uses JavaScript's return-override feature to return an arbitrary object from the constructor.

7. Set element's custom element state to "customized".
8. For each attribute in element's attribute list, in order, enqueue a custom element callback reaction with element, callback name "attributeChangedCallback", and an argument list containing attribute's local name, null, attribute's value, and attribute's namespace.
9. If element is currently in a shadow-including document, enqueue a custom element callback reaction with element, callback name "connectedCallback", and an empty argument list.

To try to upgrade an element, given as input an element element, run the following steps:

1. Let document be element's node document.
2. Let is be the value of the attribute in element's attribute list whose qualified name is "is", if any such attribute exists, or null otherwise.
3. Let definition be the result of looking up a custom element definition given document, element's namespace, element's local name, and is.
4. If definition is not null, enqueue a custom element upgrade reaction given element and definition.

Custom element reactions

A custom element possesses the ability to respond to certain occurrences by running author code:

• When upgraded, its constructor is run.
• When it is inserted in a shadow-including document, its connectedCallback is run.
• When it is in a shadow-including document and removed, its disconnectedCallback is run.
• When any of its attributes are changed, appended, removed, or replaced, its attributeChangedCallback is run.

We call these reactions collectively custom element reactions.

The way in which custom element reactions are invoked is done with special care, to avoid running author code during the middle of delicate operations. Effectively, they are delayed until "just before returning to user script". This means that for most purposes they appear to execute synchronously, but in the case of complicated composite operations (like cloning, or range manipulation), they will instead be delayed until after all the relevant user agent processing steps have completed, and then run together as a batch.

Additionally, the precise ordering of these reactions is managed via a somewhat-complicated stack-of-queues system, described below. The intention behind this system is to guarantee that custom element reactions always are invoked in the same order as their triggering actions, at least within the local context of a single custom element. (Because custom element reaction code can perform its own mutations, it is not possible to give a global ordering guarantee across multiple elements.)

Each unit of related similar-origin browsing contexts has a custom element reactions stack, which is initially empty. Each item in the stack is an element queue, which is initially empty as well; the element queue at the top of the stack is called the current element queue. Each item in an element queue is an element. (The elements are not necessarily custom yet, since this queue is used for upgrades as well.)

All elements have an associated custom element reaction queue, initially empty. Each item in the custom element reaction queue is of one of two types:

• An upgrade reaction, which will upgrade the custom element and contains a custom element definition; or
• A callback reaction, which will call a lifecycle callback, and contains a callback function as well as a list of arguments.

This is all summarized in the following schematic diagram:

To enqueue a custom element callback reaction, given a custom element element, a callback name callbackName, and a list of arguments args, run the following steps:

1. Let document be element's node document.
2. If document does not have a browsing context, abort these steps.
3. Let registry be document's associated Window's CustomElementsRegistry object.
4. Let definition be the the entry in registry with name equal to element's local name.

   This algorithm can only be called when such a definition exists.

5. Let callback be the value of the entry in definition's lifecycle callbacks with key callbackName.
6. If callback is undefined, abort these steps.

7. If callbackName is "attributeChangedCallback":

   1. Let attributeName be the the first element of args.
   2. If definition's observed attributes does not contain attributeName, abort these steps.
8. Add a new callback reaction to element's custom element reaction queue, with callback function callback and arguments args.
9. Add element to the current element queue.

To enqueue a custom element upgrade reaction, given an element element and custom element definition definition, run the following steps:

1. Add a new upgrade reaction to element's custom element reaction queue, with custom element definition definition.
2. Add element to the current element queue.

To invoke custom element reactions in an element queue queue, run the following steps:

1. For each custom element element in queue:

   1. Let reactions be element's custom element reaction queue.

   2. Repeat until reactions is empty:

      1. Remove the first element of reactions, and let reaction be that element. Switch on reaction's type:

         upgrade reaction

         Upgrade element using reaction's custom element definition.

         callback reaction

         Invoke reaction's callback function with reaction's arguments, and with element as the callback this value.

         If this throws any exception, report the exception.

The following needs to be formalized more; see #186.

Any time a script calls a method, reads or sets a property that is implemented by the user agent, the following actions MUST occur:

• When transitioning from script to the user agent code, push a new element queue to the custom element reactions stack
• When transitioning back from the user agent code to script, pop the element queue from the custom element reactions stack and invoke custom element reactions in that queue.

HTML+: The Window object

HTML's Window object definition must be extended as follows:

partial interface Window {
    readonly attribute CustomElementsRegistry customElements;
};

As is conventional for HTML, the actual definition of this property is elsewhere in the specification (cf. location and history). We have it above in the section "The CustomElementsRegistry interface".

HTML+: Element interfaces

HTML currently does not do a great job of defining DOM's element interface concept. There is a definition hidden inside the parser, but it isn't explicit that this also covers other element creation cases. We should create a section that is more explicit, and it should roughly contain the following (including the note afterward):

The element interface for an element with name name in the HTML namespace is determined as follows:

1. If this specification defines an interface appropriate for the element type corresponding to the tag name name, return that interface.
2. If other applicable specifications define such an appropriate interface for name, return the interface they define.
3. If name is a valid custom element name, return HTMLElement.
4. Otherwise, return HTMLUnknownElement.

The use of HTMLElement instead of HTMLUnknownElement in the case of valid custom element names is done to ensure that any potential future upgrades only cause a linear transition of the element's prototype chain, from HTMLElement to a subclass, instead of a lateral one, from HTMLUnknownElement to an unrelated subclass.

HTML+: Pseudo-classes

The following should be added to HTML's pseudo-classes section.

:defined

The :defined pseudo-class must match any element that is defined.

HTML+: The HTMLElement constructor

The HTMLElement interface gains following annotation:

[Constructor]

We then add the following definition:

1. Let realm be the result of GetFunctionRealm(the currently executing HTMLElement function).
2. Let registry be realm's [[\GlobalObject]]'s CustomElementsRegistry object.
3. Let definition be the entry in registry with constructor equal to NewTarget. If there is no such definition, throw a TypeError and abort these steps.

4. If definition's construction stack is empty, perform the following substeps:

   1. Let localName be the definition's local name.
   2. Return a new element that implements HTMLElement, with no attributes, namespace set to the HTML namespace, local name set to localName, and node document set to document.

   This occurs when author script constructs a new custom element directly, e.g. via new MyCustomElement().

5. Let instance be the last entry in definition's construction stack.

6. If instance is an already constructed marker, throw an InvalidStateError and abort these steps.

   This can occur when the author code inside the custom element constructor invokes super() multiple times.

7. Let prototype be definition's prototype.
8. Perform element.[[\SetPrototypeOf]](prototype). Rethrow any exceptions.
9. Replace the last entry in definition's construction stack with an already constructed marker.

10. Return instance.

    This step is normally reached when upgrading a custom element; the existing element is returned, so that the super() call inside the custom element constructor assigns that existing element to this.

For now, the HTMLElement constructor cannot be invoked directly. It only works when used via a super() call inside a custom element constructor.

HTML+: Parsing HTML documents

The create an element for a token algorithm should be adjusted by replacing step 1 with the following steps, and adjusting further steps to refer to element instead of "the element" or "the newly created element".

1. Let document be intended parent's node document.
2. Let local name be the tag name of the token.
3. Let is be the value of the "is" attribute in the given token, if such an attribute exists, or null otherwise.
4. Let definition be the result of looking up a custom element definition given document, given namespace, local name, and is.
5. If definition is non-null and the parser was not originally created for the HTML fragment parsing algorithm, let will execute script be true. Otherwise, let it be false.

6. If will execute script is true:

   1. Increment the parser's script nesting level.
   2. Set the parser pause flag to true.
   3. If the JavaScript execution context stack is empty, perform a microtask checkpoint.
   4. Push a new element queue onto the custom element reactions stack.

7. Let element be the result of creating an element given document, localName, null, given namespace, and is. If will execute script is true, set the synchronous custom elements flag; otherwise, leave it unset.

   This will cause custom element constructors to run, if will execute script is true. However, even if this causes new characters to be inserted into the tokenizer, the parser will not be executed reentrantly, since the parser pause flag is true. Similarly, blowing away the document is not possible, since the script nesting level is greater than zero.

   If this step throws an exception, report the exception, and let element be instead a new element that implements HTMLUnknownElement, with no attributes, namespace set to given namespace, namespace prefix set to null, custom element state "undefined", and node document set to document.

8. Append each attribute in the given token to element.

   This can enqueue a custom element callback reaction for the attributeChangedCallback, which might run immediately (in the next step).

   Even though the "is" attribute governs the creation of a type extension, it is not present during the execution of the relevant custom element constructor; it is appended in this step, along with all other attributes.

9. If will execute script is true:

   1. Let queue be the result of popping the current element queue from the custom element reactions stack. (This will be the same element queue as was pushed above.)
   2. Invoke custom element reactions in queue.
   3. Decrement the script nesting level by one.
   4. If the parser's script nesting level is zero, then set the parser pause flag to false.

HTML+: Parsing XHTML documents

It turns out there's not actually a spec for the XML parser. Awesome! (Not actually awesome.) The HTML Standard has a nice vague paragraph about "This Document must then be populated with DOM nodes that represent the tree structure of the input passed..." which should get something like the following inserted (probably by inserting it after the first sentence, then splitting the mutation events/observers prose into a new paragraph).

When creating DOM nodes representing elements, the create an element for a token algorithm or some equivalent that operates on appropriate XML datastructures must be used, to ensure the proper element interfaces are created and that custom elements are set up correctly.

HTML+: Content Model Updates

HTML has several sections that need to be updated when introducing a new element, or in this case class of elements. Those are:

• The categories venn diagram's interactive list should include custom elements in phrasing and flow content.
• Flow content should include custom elements
• Phrasing content should include custom elements
• Palpable content should include custom elements
• The elements index should include a row at the bottom for custom elements
• The element content categories index should include custom elements in the flow content, phrasing content, and palpable content sections.

DOM+: Elements

The Element interface section will need to be modified as follows. The paragraph listing the values associated with an element should be modified to read as follows, including the note afterward:

Elements have an associated namespace, namespace prefix, local name, and custom element state. When an element is created, all of these values are initialized.

An element's custom element state is one of "undefined", "uncustomized", or "custom". An element whose custom element state is either "uncustomized" or "custom" is said to be defined. An element whose custom element state is "custom" is said to be custom.

Whether or not an element is defined is used to determine the behavior of the :defined pseudo-class. Whether or not an element is custom is used to determine the behavior of the mutation algorithms.

<!DOCTYPE html>
<script>
  window.customElements.define("sw-rey", class extends HTMLElement {})
  window.customElements.define("sw-finn", class extends HTMLElement {}, { extends: "p" })
  window.customElements.define("sw-kylo", class extends HTMLElement {
    constructor() {
      super()
      throw new Error("The droid... stole a freighter?")
    }
  })
</script>

<!-- "undefined" (not defined, not custom) -->
<sw-han></sw-han>
<sw-kylo></sw-kylo>
<p is="sw-luke"></p>
<p is="asdf"></p>

<!-- "uncustomized" (defined, not custom) -->
<p></p>
<asdf></asdf>

<!-- "custom" (defined, custom) -->
<sw-rey></sw-rey>
<p is="sw-finn"></p>

Additionally, after the talk about qualified names but before the discussion of attributes, the following algorithm should be inserted:

To create an element, given a document, prefix, localName, namespace, is, and optional synchronous custom elements flag, run the following steps:

1. Let result be null.
2. Let definition be the result of looking up a custom element definition given document, namespace, localName, and is.

3. If definition is non-null, and definition's name is not equal to its local name (i.e. definition represents a type extension), then:

   1. Let interface be the element interface for localName and the HTML namespace.
   2. Set result to a new element that implements interface, with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state "undefined", and node document set to document.
   3. If the synchronous custom elements flag is set, upgrade element using definition.
   4. Otherwise, enqueue a custom element upgrade reaction given result and definition.

4. Otherwise, if definition is non-null, then:

   1. If synchronous custom elements flag is set:

      1. Let C be definition's constructor.
      2. Set result to Construct(C). Rethrow any exceptions.

      3. If result does not implement the HTMLElement interface, throw a TypeError exception.

         This is meant to be a brand check to ensure that the object was allocated by the HTMLElement constructor. Eventually Web IDL may give us a more precise way to do brand checks.

      4. If the value of result's [[\Prototype]] internal slot is not equal to definition's prototype, throw a TypeError exception.
      5. If result's attribute list is not empty, throw a NotSupportedError exception.
      6. If result has children, throw a NotSupportedError exception.
      7. If result's parent is not null, throw a NotSupportedError exception.
      8. If result's node document is not document, throw a NotSupportedError exception.
      9. If result's namespace is not the HTML namespace, throw a NotSupportedError exception.
      10. If result's local name is not localName, throw a NotSupportedError exception.
      11. Set result's namespace prefix to prefix.
      12. Set result's custom element state to "custom".

   2. Otherwise:

      1. Set result to a new element that implements the HTMLElement interface, with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state "undefined", and node document set document.
      2. Enqueue a custom element upgrade reaction given result and definition.

5. Otherwise:

   1. Let interface be the element interface for localName and namespace.
   2. Set result to a new element that implements interface, with no attributes, namespace set to namespace, namespace prefix set to prefix, local name set to localName, custom element state "uncustomized", and node document set to document.
   3. If document has a browsing context, namespace is the HTML namespace, and either localName is a valid custom element name or is is non-null, set result's custom element state to "undefined".
6. Return result.

DOM+: Cloning

The clone a node algorithm will need to be modified as follows. A new case, separate from the main switch, will be needed to generate copy for Elements. It should use create an element, given document, node's local name, node's namespace prefix, node's namespace, and the value of node's is attribute (if present). The synchronous custom elements flag should be unset.

DOM+: Mutation algorithms

The mutation algorithms sections need to be modified as follows to properly enqueue custom element callbacks.

Modify the insert algorithm as follows. Replace step 6.2 with:

2. For each shadow-including inclusive descendant inclusiveDescendant of node, in shadow-including tree order, run these subsubsteps:

   1. Run the insertion steps with inclusiveDescendant and parent.

   2. If inclusiveDescendant is in a shadow-including document, then:

      1. If inclusiveDescendant is custom, enqueue a custom element callback reaction with inclusiveDescendant, callback name "connectedCallback", and an empty argument list.

      2. Otherwise, try to upgrade inclusiveDescendant.

         If this successfully upgrades inclusiveDescendant, its connectedCallback will be enqueued automatically during the upgrade an element algorithm.

Modify the remove algorithm as follows. Replace step 9 with:

9. For each shadow-including inclusive descendant inclusiveDescendant of node, in shadow-including tree order, run these subsubsteps:

   1. Run the removing steps with inclusiveDescendant and parent.
   2. If inclusiveDescendant is custom and is not in a shadow-including document, enqueue a custom element callback reaction with inclusiveDescendant, callback name "disconnectedCallback", and an empty argument list.

Modify the change an attribute algorithm as follows. Add an additional step after step 1:

2. If element is custom, enqueue a custom element callback reaction with element, callback name "attributeChangedCallback", and an argument list containing attribute's local name, attribute's value, value, and attribute's namespace.

Modify the append an attribute algorithm as follows. Add an additional step after step 1:

2. If element is custom, enqueue a custom element callback reaction with element, callback name "attributeChangedCallback", and an argument list containing attribute's local name, null, attribute's value, and attribute's namespace.

Modify the remove an attribute algorithm as follows. Add an additional step after step 1:

2. If element is custom, enqueue a custom element callback reaction with element, callback name "attributeChangedCallback", and an argument list containing attribute's local name, attribute's value, null, and attribute's namespace.

Modify the replace an attribute algorithm as follows. Add an additional step after step 1:

2. If element is custom, enqueue a custom element callback reaction with element, callback name "attributeChangedCallback", and an argument list containing oldAttr's local name, oldAttr's value, newAttr's value, and oldAttr's namespace.

DOM+: Document methods

To allow creating both custom tag and type extension-style custom elements, the createElement or createElementNS methods gain optional typeExtension arguments. Their new definitions are:

partial interface Document {
    Element createElement(DOMString localName, optional ElementCreationOptions options);
    Element createElementNS(DOMString? namespace, DOMString qualifiedName, optional ElementCreationOptions options);
};

dictionary ElementCreationOptions {
    DOMString is;
};