Custom Elements

Motivations

Concepts

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

The custom element type identifies a custom element interface and is a sequence of characters that must match the NCName production, must contain a U+002D HYPHEN-MINUS character, and must not contain any uppercase ASCII letters. The custom element type 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 describes a custom element and consists of:

• custom element type,
• local name,
• namespace,
• custom element prototype, and
• lifecycle callbacks.

At the time of creation, a document could be associated with a registry. A registry is a set of element definitions.

Element registration is a process of adding an element definition to a registry. One element definition can only be registered with one registry.

If a document has a registry associated with it, then for this document and a given element definition in the registry, the custom element's interface must be the element interface for local name and namespace values of custom element type and the namespace of the element definition, respectively.

If a document does not have a registry associated with it, all attempts at element registration will fail.

The exact nature of creating registries, their association with documents, and element registration are defined further in this specification.

Custom Element Lifecycle

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

• Custom element is created before its definition is registered
• Definition of a custom element is registered
• Custom element instance is created after its definition was registered
• Custom element is inserted into active document
• Custom element is removed from active document
• Custom element's attribute is created, removed, or modified.

Various callbacks can be invoked when a custom 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:

Enqueuing and Invoking Callbacks

To facilitate invoking callbacks, each unit of related similar-origin browsing contexts has a processing stack, which is initially empty. Each item in the stack is an element queue, which is initially empty as well. Each item in the element queue is a custom element.

Each custom element has an associated callback queue and an element is being created flag. The flag is initially set to false and the callback queue is initially empty. Each item in the queue consists of the callback itself and zero or more string values that are used as callback arguments.

To invoke callbacks in an element queue, the user agent must run these steps or their equivalent:

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 processing stack
• When transitioning back from the user agent code to script, pop the element queue from the processing stack and invoke callbacks in that queue.

In addition to an element queue, there is also a sorted element queue. The custom elements are kept in the order of increasing custom element order.

The custom element order is a sum of document custom element order and import tree order, in which the import tree order is scaled so that its lowest value is always larger than the highest possible value of document custom element order.

The document custom element order is a numerical value, associated with every custom element. This value is as a result of custom element's document keeping a numerical value that is incremented and assigned to custom element as its custom element order whenever the following occurs:

• A custom element is popped from the stack of open elements
• A custom element is created with means other than a parser

The import tree order of a given custom element of an import link tree is determined by tree order in an import link tree that was flattened by replacing every import link with the content of its imported document.

The highest stable order is the value that is immediately preceeding the custom element order of an element in the first encountered import, in tree order, that has not yet completely loaded. If there is no such element, the highest stable order is the highest custom element order in the flattened import link tree.

index.html:
<link rel="import" href="import.html">
...
<me-second></me-second>
...

import.html:
<me-first></me-first>

Each unit of related similar-origin browsing contexts has an initially-empty sorted element queue, called base element queue.

Whenever a base element queue becomes non-empty, the user agent must queue a microtask to process base element queue for the unit of related similar-origin browsing contexts to which the scripts' browsing context belongs.

To prevent reentrance while processing base element queue, each unit of related similar-origin contexts has a processing base element queue flag, which must initially be false.

To process base element queue, a conforming user agent must run the following steps or their equivalent:

In the unit of related similar-origin browsing contexts to which the scripts' browsing context belongs, the current element queue is the element queue at the top of the processing stack or the base element queue if the processing stack is empty.

To enqueue a lifecycle callback, the user must run the following steps or their equivalent:

Types of Callbacks

The following callbacks are recognized:

createdCallback

This callback is invoked after custom element instance is created and its definition is registered. The actual timing of this callback is defined further in this specification.

The custom element prototype must be set just prior to invoking callback.

For the duration of this callback invocation, the element is being created flag must be set to true. In all other cases, the flag must be set to false.

If the created callback exists for an element, all other callbacks must not be enqueued until after this created callback's invocation had started.

attachedCallback

Unless specified otherwise, this callback must be enqueued whenever custom element is inserted into a document and this document has a browsing context.

detachedCallback

Unless specified otherwise, this callback must be enqueued whenever custom element is removed from the document and this document has a browsing context.

attributeChangedCallback

Unless specified otherwise, this callback must be enqueued whenever custom element's attribute is added, changed or removed. Depending on the type of attribute modification, the following additional strings are added to the queue item:

attribute is set

attribute local name, null, new attribute value, and the attribute namespace.

attribute is changed

attribute local name, old attribute value, new attribute value, and the attribute namespace.

attribute is removed

attribute local name, old attribute value, null, and the attribute namespace.

To set custom element prototype on a custom element, a conforming user agent must run the following steps or their equivalent:

Creating and Passing Registries

When an HTML Document is loaded in a browsing context, a new registry must be created and associated with this document.

A new document instance must be associated with an existing registry in these cases:

• When DOMImplementation's createDocument method is invoked with namespace set to HTML Namespace or when the createHTMLDocument method is invoked, use the registry of the associated document to the new instance.
• When creating an import, use the registry of the master document.
• When creating a template contents owner document, use a new empty registry.

In all other cases, new documents must not have a registry.

Registering Custom Elements

Because element registration can occur at any time, a custom element could be created before its definition 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 registry has an associated map of all instances of unresolved elements for a given pair of custom element type and namespace. This data structure is called the upgrade candidates map and is initially empty. Each value item in this map is a sorted element queue.

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

Registering an element definition is the responsibility of the element registration algorithm, which must be equivalent to running these steps:

The definition construction algorithm creates an element definition and must be equivalent to running these steps:

The SVGElement inheritance detection algorithm must run these steps:

The element upgrade algorithm upgrades unresolved elements whose definition is now registered and must be equivalent to running these steps:

Extensions to Document Interface

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

partial interface Document {
    Function registerElement(DOMString type, optional ElementRegistrationOptions options);
};

dictionary ElementRegistrationOptions {
     object? prototype = null;
     DOMString? extends = null;
};

When called, the registerElement method must run these steps:

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

<p is="x-foo">Paragraph of amazement</p>

var foo = document.createElement('p', 'x-foo');

Elements with SVGElement prototype deserve a special mention: using custom tag approach results in ignored elements in SVG. Thus, your SVG-based custom elements would almost always be type extensions.

Unresolved Element Pseudoclass

The :unresolved pseudoclass must match all custom elements whose created callback has not yet been invoked.

Instantiating Custom Elements

The custom element type 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 types are called custom tags.
2. As the value of the is attribute of the custom element. custom element types 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 type.

If both types of custom element types 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:

Extensions to Document Interface

To allow creating both custom tag and type extension-style custom elements, the createElement or createElementNS methods have overloads with a typeExtension argument:

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

Parsing Custom Elements

To enable instantiating custom elements during tree construction, a conforming UA must run enqueue created callback whenever creating a custom element.

Custom Elements and ECMAScript 6

Similarly, the custom element constructor generation algorithm will change as follows:

Custom Element Semantics

The default semantics of a custom element is dependent upon the form in which it is instantiated:

• by default a custom tag has no special meaning at all. It represents its children.
• by default a type extension inherits the semantics of the element type it extends.

Custom Tag Example

For example, a custom tag could be named taco-button, but the name alone does not express the semantics of a HTML button element simply due to its name. As instantiated a custom tag conveys a similar amount of semantics as an HTML div or span element:

<!-- taco-button represents a span with a fancy name -->
<taco-button></taco-button>

The addition of visual styling and scripted events to the taco-button could provide hints as to its semantics and expected interaction behaviours — for some users — but for the semantics to be formally expressed developers must convey the semantics using ARIA roles, states and properties.

The addition of a tabindex attribute to the custom element provides interaction (the element is included in the focus order) and property/state semantics (it exposes information that it is focusable and if it currently has focus).

<!-- taco-button represents a focusable span with a fancy name -->
<taco-button tabindex="0">Eat Me</taco-button>

The addition of a label, using aria-label, to the custom element provides an Accessible Name for the element.

<!-- taco-button represents a focusable span with a fancy name and a text label -->
<taco-button tabindex="0" aria-label="Eat Me">Eat Me</taco-button>

The addition of keyboard event handlers to the custom element element provides the means for keyboard users to operate the control, but does not convey the presence of the functionality.

<!-- taco-button represents focusable span with a fancy name, a text label and button like event handling -->
<taco-button tabindex="0" onclick="alert('tasty eh?');"
onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>

The addition of inline event handlers are for demonstration purposes only. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all. This example demonstrates one method for developers to ensure that a custom control is operable for keyboard users and meets the WCAG 2.0 criteria "All functionality of the content is operable through a keyboard interface".

The addition of an ARIA role="button" conveys the custom element's role semantics, which enables users to successfully interact with the control using the expected button interaction behaviours (pressing the space or enter keys to activate).

<!-- taco-button represents a focusable button with a text label and button like event handling -->
<taco-button role="button" tabindex="0" onclick="alert('tasty eh?');"
onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>

The developer may provide a disabled state for the custom element. This could be implemented by removing the tabindex attribute so the element is no longer included in the focus order and removing the functionality so that interacting with the element does nothing. Also the visual styling may also be modified to visually indicate it the element is disabled.

<!-- grayed out non focusable taco-button with functionality removed, to indicate the button is in a disabled state  -->
<taco-button role="button" tabindex="0" onclick="alert('tasty eh?');" 
onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>

Removing the focusability and functionality of the custom element and modifying its style does not unambiguously express that it is in a disabled state. To unambiguously express the disabled state add aria-disabled="true".

A disabled attribute would not work here as the custom tag is not based on an HTML element that suports its use.

<!-- taco-button represents a focusable button with a text label and button like event handling -->
<taco-button role="button" tabindex="0" onclick="alert('tasty eh?');" 
onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};" aria-disabled="true">Eat Me</taco-button>

Type Extension Example

A type extension, for example could extend the HTML button element. As instantiated it would inherit the button element's name, role, states and properties, built in focus and keyboard interaction behaviours.

<!-- tequila-button represents a button with an accessible name of "Drink Me!" -->
<button is="tequila-button">Drink Me!</button>

To implement the desired tequila-button feature, all that is required is the addition of an event handler. The rest of the semantics and interaction behaviour are provided by the browser as part of its implementation of the button element.

<!-- tequila-button represents a button -->
<button is="tequila-button" onclick="alert('smooth!');">Drink Me!</button>

To implement the disabled state on the tequila-button, all that is required is the addition of the HTML disabled attribute. The semantics, style and interaction behaviour are implemented by the browser.

<!-- tequila-button represents a button -->
<button is="tequila-button" onclick="alert('smooth!');" disabled>Drink Me!</button>

Custom Element Semantics — Conclusion

The simplest and most robust method to create custom elements that are usable and accessible is to implement custom elements as type extensions. This method provides a custom element with built in semantics and interaction behaviours that developers can use as a foundation.

Use ARIA, where needed, to provide semantics for custom elements and follow the ARIA Design Patterns when implementing ARIA attributes and UI interaction behaviours. Ensure that custom tag or type extension custom elements meet the criteria listed in the Custom Control Accessible Development Checklist. Use ARIA in accordance with the Document conformance requirements for use of ARIA attributes in HTML.

Further Reading for Developers

• WAI-ARIA 1.0 Authoring Practices
• Using ARIA in HTML

Appendix A: All Algorithms in One Diagram