Custom Elements

Terminology

Custom element is platform object whose interface is defined by the author. This interface must inherit from the Element interface. The interface prototype object of a custom element's interface is called the custom element prototype.

The custom element name identifies a custom element and is a sequence of alphanumeric ASCII characters that must match the NCName production and contain a U+002D HYPHEN-MINUS character. The custom element name must not be one of the following values:

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

The element definition is an association of a custom element name, local name and a namespace with a custom element prototype, and lifecycle callbacks.

Custom Element Lifecycle

A custom element can go through these changes during its lifetime:

1. Custom element is created before its custom element definition is associated with the document
2. Definition of a custom element is associated with the document
3. Custom element instance is created after its definition was associated with the document
4. Custom element is inserted into a document
5. Custom element is removed from the document
6. Custom element is garbage-collected.

A custom element can optionally implement several callbacks that are invoked when the element goes through some of these changes. These callbacks are stored internally as a collection of key-value pairs and called lifecycle callbacks.

To transfer a callback named name from an object property named property to lifecycle callbacks, the user agent must run the following steps:

To retrieve a callback named name for an element, the user agent must run the following steps:

Each unit of related similar-origin browsing contexts has an associated lifecycle callbacks queue, which is initially empty. Each item in the queue consists of the callback and the callback this value.

Also, each unit of related similar-origin contexts has a running lifecycle callbacks flag, which must initially be false. It is used to prevent reentrant invocation of the algorithm to invoke lifecycle callbacks.

To invoke lifecycle callbacks, a conforming user agent must run the following steps or their equivalent:

The following callbacks are recognized:

ready

invoked after custom element instance is created and its definition is associated with the document. The actual timing of this callback is defined further in this specification.

inserted

Unless specified otherwise, this callback must placed into the lifecycle callbacks queue with the callback this value of the custom element whenever custom element is inserted into a document.

removed

Unless specified otherwise, this callback must placed into the lifecycle callbacks queue with the callback this value of the custom element whenever custom element is removed from the document.

Registering Custom Elements

Element registration is a process of associating an element definition with a document. An element definition can only be registered with one document. Once registered, the custom element's interface must be the element interface for local name and namespace values of custom element name and the namespace in custom element definition, respectively.

Because element registration can occur at any time, a custom element could be created before it is registered. Such custom element instances are called unresolved elements. When an unresolved element is created, and if its element interface was not defined by HTML or other applicable specifications, the unresolved element's element interface must be:

• the HTMLElement, if the namespace is HTML Namespace;
• the SVGElement, if namespace is SVG Namespace; or
• unknown, otherwise.

Each browsing context has an associated map of all instances of unresolved elements for a given pair of custom element name and namespace. This data structure is called the upgrade candidates map and is initially empty.

Whenever an unresolved element is created, it must be added to the upgrade candidates map.

As an element definition is registered, all corresponding unresolved elements are upgraded using the element upgrade algorithm, which must be equivalent to running these steps:

The register method of the Document interface provides a way to register a custom element and returns its custom element constructor.

partial interface Document {
    Function register(DOMString name, optional ElementRegistrationOptions options);
};

dictionary ElementRegistrationOptions {
     object? prototype = null;
};

When called, the register method must run these steps:

document.register('x-foo', {
    prototype: Object.create(HTMLParagraphElement.prototype, {
        firstMember: {
            get: function() { return foo; },
            enumerable: true,
            configurable: true
        },
        // specify more members for your prototype.
        // ...
    })
});

Unresolved Element Pseudoclass

The :unresolved pseudoclass must match all unresolved elements.

Instantiating Custom Elements

The custom element name is given to a custom element at the time of its instantation in one of the two ways:

1. As the local name of the custom element. These types of custom element names are called custom tags.
2. As the value of the is attribute of the custom element. Custom element names given this way are called type extensions.

After a custom element is instantiated, changing the value of the is attribute must not affect this element's custom element name.

If both types of custom element names are provided at the time of element's instantiation, the custom tag must win over the type extension.

All custom elements must be constructable with a function object, called custom element constructor. This constructor must be created with the custom element constructor generation algorithm, which must be equivalent to running these steps:

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

The element initialization algorithm must be equivalent to running these steps:

Serializing and Parsing Custom Elements in HTML

To enable instantiating custom elements during tree construction, a conforming UA must run these steps when creating an element for a token:

In addition, just before the user agent is to perform a microtask checkpoint, the user agent must invoke lifecycle callbacks for the unit of related similar-origin browsing contexts to which the scripts' browsing context belongs.

The custom elements must be serialized like any HTML elements.

Declaring Custom Elements

Specify how custom elements are defined declaratively.