1. 4.13 カスタム要素
      1. 4.13.1 導入
        1. 4.13.1.1 自律カスタム要素の作成
        2. 4.13.1.2 カスタマイズされた組み込み要素の作成
        3. 4.13.1.3 自律カスタム要素の欠点
        4. 4.13.1.4 Upgrading elements after their creation
      2. 4.13.2 Requirements for custom element constructors
      3. 4.13.3 Core concepts
      4. 4.13.4 The CustomElementRegistry interface
      5. 4.13.5 Upgrades
      6. 4.13.6 Custom element reactions

4.13 カスタム要素

Support: custom-elementsv1Chrome for Android (limited) 61+Chrome (limited) 54+iOS Safari (limited) 10.3+UC Browser for Android NoneFirefox NoneSamsung Internet (limited) 5+IE NoneOpera Mini NoneSafari (limited) 10.1+Android Browser (limited) 56+Opera (limited) 41+

Source: caniuse.com

4.13.1 導入

この節は非規範的である。

カスタム要素は、著者に完全に機能するDOM要素を独自に構築する方法を提供する。スクリプティングなどで事後に追加されたアプリケーション固有の動作とともに、著者は文書内で非標準要素を常に使用することができたが、そのような要素は歴史的に不適合であり、あまり機能しなかった。カスタム要素を定義することで、著者はパーサーに要素を正しく構成する方法と、そのクラスの要素が変更にどのように反応するかを通知できる。

カスタム要素は、(カスタム要素の定義のような)低レベルの著者公開拡張ポイントに関して、(HTMLの要素のような)既存のプラットフォーム機能を説明することによって、"プラットフォームを合理化する"ための大きな努力の一部である。今日、HTMLの既存要素の振る舞いを完全に説明することを妨げるカスタム要素(機能的および意味的な要素)の機能には多くの制限があるが、我々は時間の経過とともにこのギャップを縮小したいと思う。

4.13.1.1 自律カスタム要素の作成

この節は非規範的である。

自律カスタム要素を作成する方法を説明するために、国旗の小さなアイコンのレンダリングをカプセル化するカスタム要素を定義してみよう。私たちの目標は、次のように使用できるようにすることである:

<flag-icon country="nl"></flag-icon>

これを行うには、まずカスタム要素のクラスを宣言し、HTMLElementを拡張する:

class FlagIcon extends HTMLElement {
  constructor() {
    super();
    this._countryCode = null;
  }

  static get observedAttributes() { return ["country"]; }

  attributeChangedCallback(name, oldValue, newValue) {
    // name will always be "country" due to observedAttributes
    this._countryCode = newValue;
    this._updateRendering();
  }
  connectedCallback() {
    this._updateRendering();
  }

  get country() {
    return this._countryCode;
  }
  set country(v) {
    this.setAttribute("country", v);
  }

  _updateRendering() {
    // Left as an exercise for the reader. But, you'll probably want to
    // check this.ownerDocument.defaultView to see if we've been
    // inserted into a document with a browsing context, and avoid
    // doing any work if not.
  }
}

次に、要素を定義するために次のクラスを使用して必要がある:

customElements.define("flag-icon", FlagIcon);

この時点で、上記のコードは動作する。flag-iconタグを見るたびに、パーサーはFlagIconクラスの新しいインスタンスを作成し、要素の内部状態を設定し、レンダリングを更新するために使用する(適切な場合)、新しいcountry属性についてコードに伝える。

DOM APIを使用してflag-icon要素を作成することもできる:

const flagIcon = document.createElement("flag-icon")
flagIcon.country = "jp"
document.body.appendChild(flagIcon)

最後に、カスタム要素コンストラクタ自体を使用することもできる。つまり、上記のコードは次のコードと同じである:

const flagIcon = new FlagIcon()
flagIcon.country = "jp"
document.body.appendChild(flagIcon)
4.13.1.2 カスタマイズされた組み込み要素の作成

この節は非規範的である。

カスタマイズされた組み込み要素は、自律カスタム要素とはわずかに異なる定義があり、そして大きく異なる使われ方をする、独自の種類のカスタム要素である。この要素は、新しいカスタム機能でHTMLの既存要素を拡張することで、HTMLの既存要素由来の動作の再利用を可能にするために存在する。残念なことに、HTML要素の既存の動作の多くが自律カスタム要素を純粋に使用して複製できないため、これは重要である。代わりに、カスタマイズされた組み込み要素は、既存の要素にカスタム構築動作、ライフサイクルフック、およびプロトタイプチェーンをインストールを可能にし、既存の要素の上にこれらの機能を本質的に"混在"させる。

カスタマイズされた組み込み要素は、ユーザーエージェントや他のソフトウェアが要素のセマンティクスおよび動作を識別するために要素のローカル名として扱うので、自律カスタム要素とは異なる構文を必要とする。つまり、既存の動作の上に構築するカスタマイズされた組み込み要素の概念は、元のローカル名を保持する拡張要素に決定的に依存する。

この例において、plastic-buttonというカスタマイズされた組み込み要素を作成する。これは通常のボタンのように動作するが、クリックするたびにファンシーなアニメーション効果が追加される。今回はHTMLElementの代わりにHTMLButtonElementを拡張するが、前と同じようにクラスを定義することから始める:

class PlasticButton extends HTMLButtonElement {
  constructor() {
    super();

    this.addEventListener("click", () => {
      // Draw some fancy animation effects!
    });
  }
}

カスタム要素を定義する場合、extendsオプションも指定する必要がある:

customElements.define("plastic-button", PlasticButton, { extends: "button" });

一般に、拡張されている要素の名前は、同じインターフェイスを共有する要素(HTMLQuoteElementを共有するqblockquoteの両者など)を共有するため、拡張する要素インターフェイスを単に調べるだけでは判断することができない。

カスタマイズされた組み込み要素を使用するには、button要素でis属性を使用する:

<button is="plastic-button">Click Me!</button>

カスタマイズされた組み込み要素自律カスタム要素として使用しようとするとうまくいかない。つまり、<plastic-button>Click me?</plastic-button>は特別な動作をしないHTMLElementを作成するだけである。

プログラムで型拡張した要素を作成する必要がある場合、次のcreateElement()の形式を使用することができる:

const plasticButton = document.createElement("button", { is: "plastic-button" });
plasticButton.textContent = "Click me!";

前と同じように、コンストラクタも動作する:

const plasticButton2 = new PlasticButton();
console.log(plasticButton2.localName);          // will output "button"
console.log(plasticButton2.getAttribute("is")); // will output "plastic-button"

特に、buttonが特別であるすべての方法は、そのような"プラスチックボタン"にも適用される:フォーカス動作、フォーム送信に関与する能力、disabled属性など。

カスタマイズされた組み込み要素は、有用なユーザーエージェントが提供する動作またはAPIを持つ既存のHTML要素を拡張を可能にするように設計されている。そのため、この仕様で定義される既存のHTML要素のみを拡張することができ、要素インターフェイスとしてHTMLUnknownElementを使用するように定義されたbgsoundblinkisindexkeygenmulticolnextid、またはspacerなどのレガシー要素は拡張できない。

この要件の1つの理由は将来の互換性である。もしカスタマイズされた組み込み要素が、たとえばcomboboxのような、現在不明の要素を拡張したものが定義されたなら、派生したカスタマイズされた組み込み要素のコンシューマーが、ユーザーエージェント提供の動作に興味を持たない基本要素に依存するようになるため、これはこの仕様が将来combobox要素を定義することを妨げるかもしれない。

4.13.1.3 自律カスタム要素の欠点

この節は非規範的である。

以下で規定されているように、そして上記で触れたように、単にtaco-buttonという要素を定義して使用しても、そのような要素がボタンを表すことを意味しない。つまり、ウェブブラウザー、検索エンジン、アクセシビリティ技術などのツールは、定義された名前だけに基づいて、結果の要素をボタンとして自動的に処理しない。

自律カスタム要素を依然として使用する一方で、様々なユーザーに所望のボタンセマンティクスを伝えるためためには、複数の技術を用いる必要がある:

これらの点を念頭に置いて、(無効にする機能を含む)ボタンのセマンティクスを伝える責任を負ったフル機能のtaco-buttonは、次のようになる:

class TacoButton extends HTMLElement {
  static get observedAttributes() { return ["disabled"]; }

  constructor() {
    super();

    this.addEventListener("keydown", e => {
      if (e.keyCode === 32 || e.keyCode === 13) {
        this.dispatchEvent(new MouseEvent("click", {
          bubbles: true,
          cancelable: true
        }));
      }
    });

    this.addEventListener("click", e => {
      if (this.disabled) {
        e.preventDefault();
        e.stopPropagation();
      }
    });

    this._observer = new MutationObserver(() => {
      this.setAttribute("aria-label", this.textContent);
    });
  }

  connectedCallback() {
    this.setAttribute("role", "button");
    this.setAttribute("tabindex", "0");

    this._observer.observe(this, {
      childList: true,
      characterData: true,
      subtree: true
    });
  }

  disconnectedCallback() {
    this._observer.disconnect();
  }

  get disabled() {
    return this.hasAttribute("disabled");
  }

  set disabled(v) {
    if (v) {
      this.setAttribute("disabled", "");
    } else {
      this.removeAttribute("disabled");
    }
  }

  attributeChangedCallback() {
    // only is called for the disabled attribute due to observedAttributes
    if (this.disabled) {
      this.removeAttribute("tabindex");
      this.setAttribute("aria-disabled", "true");
    } else {
      this.setAttribute("tabindex", "0");
      this.setAttribute("aria-disabled", "false");
    }
  }
}

このようにかなり複雑な要素定義があっても、その要素はコンシューマーのために使用する喜びとはならない。自身の意志のtabindexaria-*属性を継続的に"発芽"させる。これは、現在のところ、(通常はコンシューマーがデフォルトの動作を上書きできるように予約されているにもかかわらず)これらの属性を強制的に使用する必要があり、カスタム要素に対するデフォルトのアクセシビリティセマンティクスやフォーカス動作を指定する方法が存在しないためである。

対照的に、前節で示したように、単一のカスタマイズされた組み込み要素は、button要素のセマンティクスと動作を自動的に継承する。これらの動作を手動で実装する必要はない。一般に、HTMLの既存要素の上に構築される重要な動作やセマンティクスを持つ要素については、カスタマイズされた組み込み要素の開発、保守、および消費が容易になる。

4.13.1.4 Upgrading elements after their creation

この節は非規範的である。

Because element definition can occur at any time, a non-custom element could be created, and then later become a custom element after an appropriate definition is registered. We call this process "upgrading" the element, from a normal element into a custom element.

Upgrades enable scenarios where it may be preferable for custom element definitions to be registered after relevant elements has been initially created, such as by the parser. They allow progressive enhancement of the content in the custom element. For example, in the following HTML document the element definition for img-viewer is loaded asynchronously:

<!DOCTYPE html>
<html lang="en">
<title>Image viewer example</title>

<img-viewer filter="Kelvin">
  <img src="images/tree.jpg" alt="A beautiful tree towering over an empty savannah">
</img-viewer>

<script src="js/elements/img-viewer.js" async></script>

The definition for the img-viewer element here is loaded using a script element marked with the async attribute, placed after the <img-viewer> tag in the markup. While the script is loading, the img-viewer element will be treated as an undefined element, similar to a span. Once the script loads, it will define the img-viewer element, and the existing img-viewer element on the page will be upgraded, applying the custom element's definition (which presumably includes applying an image filter identified by the string "Kelvin", enhancing the image's visual appearance).


Note that upgrades only apply to elements in the document tree. (Formally, elements that are connected.) An element that is not inserted into a document will stay un-upgraded. An example illustrates this point:

<!DOCTYPE html>
<html lang="en">
<title>Upgrade edge-cases example</title>

<example-element></example-element>

<script>
  "use strict";

  const inDocument = document.querySelector("example-element");
  const outOfDocument = document.createElement("example-element");

  // Before the element definition, both are HTMLElement:
  console.assert(inDocument instanceof HTMLElement);
  console.assert(outOfDocument instanceof HTMLElement);

  class ExampleElement extends HTMLElement {}
  customElements.define("example-element", ExampleElement);

  // After element definition, the in-document element was upgraded:
  console.assert(inDocument instanceof ExampleElement);
  console.assert(!(outOfDocument instanceof ExampleElement));

  document.body.appendChild(outOfDocument);

  // Now that we've moved the element into the document, it too was upgraded:
  console.assert(outOfDocument instanceof ExampleElement);
</script>

4.13.2 Requirements for custom element constructors

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

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. This is true even if the work is done inside a constructor-initiated microtask, as a microtask checkpoint can occur immediately after construction.

4.13.3 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. An autonomous custom element, which is defined with no extends option. These types of custom elements have a local name equal to their defined name.

  2. A customized built-in element, which is defined with an extends option. These types of custom elements have a local name equal to the value passed in their extends option, and their defined name is used as the value of the is attribute, which therefore must be a valid custom element name.

After a custom element is created, changing the value of the is attribute does not change the element's behavior, as it is saved on the element as its is value.

Autonomous custom elements have the following element definition:

カテゴリー
フローコンテンツ
フレージングコンテンツ
パルパブルコンテンツ
この要素を使用できるコンテキスト
フレージングコンテンツが期待される場所。
コンテンツモデル
透過的
コンテンツ属性
Global attributes, except the is attribute
名前空間を持たないその他の属性(文参照)。
DOMインターフェイス
Supplied by the element's author (inherits from HTMLElement)

An autonomous custom element does not have any special meaning: it represents its children. A customized built-in element inherits the semantics of the element that it extends.

Any namespace-less attribute that is relevant to the element's functioning, as determined by the element's author, may be specified on an autonomous custom element, so long as the attribute name is XML-compatible and contains no ASCII upper alphas. The exception is the is attribute, which must not be specified on an autonomous custom element (and which will have no effect if it is).

Customized built-in elements follow the normal requirements for attributes, based on the elements they extend. To add custom attribute-based behavior, use data-* attributes.


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

These requirements ensure a number of goals for valid custom element names:

Apart from these restrictions, a large variety of names is allowed, to give maximum flexibility for use cases like <math-α> or <emotion-😍>.

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

A name
A valid custom element name
A local name
A local name
A constructor
A Web IDL Function callback function type value wrapping the custom element constructor
A list of observed attributes
A sequence<DOMString>
A collection of lifecycle callbacks
A map, whose four keys are the strings "connectedCallback", "disconnectedCallback", "adoptedCallback", and "attributeChangedCallback". The corresponding values are either a Web IDL Function callback function type value, or null. By default the value of each entry is null.
A construction stack
A list, initially empty, that is manipulated by the upgrade an element algorithm and the HTML element constructors. Each entry in the list will be either an element or an already constructed marker.

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 browsing context's Window's CustomElementRegistry 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.

4.13.4 The CustomElementRegistry interface

Each Window object is associated with a unique instance of a CustomElementRegistry 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 CustomElementRegistry object for that Window object.

[Exposed=Window]
interface CustomElementRegistry {
  [CEReactions] void define(DOMString name, Function constructor, optional ElementDefinitionOptions options);
  any get(DOMString name);
  Promise<void> whenDefined(DOMString name);
};

dictionary ElementDefinitionOptions {
  DOMString extends;
};

Every CustomElementRegistry 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.

Every CustomElementRegistry also has an element definition is running flag which is used to prevent reentrant invocations of element definition. It is initially unset.

Every CustomElementRegistry also has a when-defined promise map, mapping valid custom element names to promises. It is used to implement the whenDefined() method.

window . customElements . define(name, constructor)
Defines a new custom element, mapping the given name to the given constructor as an autonomous custom element.
window . customElements . define(name, constructor, { extends: baseLocalName })
Defines a new custom element, mapping the given name to the given constructor as a customized built-in element for the element type identified by the supplied baseLocalName. A "NotSupportedError" DOMException will be thrown upon trying to extend a custom element or an unknown element.
window . customElements . get(name)
Retrieves the custom element constructor defined for the given name. Returns undefined if there is no custom element definition with the given name.
window . customElements . whenDefined(name)
Returns a promise that will be fulfilled when a custom element becomes defined with the given name. (If such a custom element is already defined, the returned promise will be immediately fulfilled.) Returns a promise rejected with a "SyntaxError" DOMException if not given a valid custom element name.

Element definition is a process of adding a custom element definition to the CustomElementRegistry. 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, then throw a TypeError and abort these steps.

  2. If name is not a valid custom element name, then throw a "SyntaxError" DOMException and abort these steps.

  3. If this CustomElementRegistry contains an entry with name name, then throw a "NotSupportedError" DOMException and abort these steps.

  4. If this CustomElementRegistry contains an entry with constructor constructor, then throw a "NotSupportedError" DOMException 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, then:

    1. If extends is a valid custom element name, then throw a "NotSupportedError" DOMException.

    2. If the element interface for extends and the HTML namespace is HTMLUnknownElement (e.g., if extends does not indicate an element definition in this specification), then throw a "NotSupportedError" DOMException.

    3. Set localName to extends.

  8. If this CustomElementRegistry's element definition is running flag is set, then throw a "NotSupportedError" DOMException and abort these steps.

  9. Set this CustomElementRegistry's element definition is running flag.

  10. Run the following substeps while catching any exceptions:

    1. Let prototype be Get(constructor, "prototype"). 例外を再度投げる。

    2. If Type(prototype) is not Object, then throw a TypeError exception.

    3. Let lifecycleCallbacks be a map with the four keys "connectedCallback", "disconnectedCallback", "adoptedCallback", and "attributeChangedCallback", each of which belongs to an entry whose value is null.

    4. For each of the four keys callbackName in lifecycleCallbacks, in the order listed in the previous step:

      1. Let callbackValue be Get(prototype, callbackName). 例外を再度投げる。

      2. If callbackValue is not undefined, then set the value of the entry in lifecycleCallbacks with key callbackName to the result of converting callbackValue to the Web IDL Function callback type. Rethrow any exceptions from the conversion.

    5. Let observedAttributes be an empty sequence<DOMString>.

    6. If the value of the entry in lifecycleCallbacks with key "attributeChangedCallback" is not null, then:

      1. Let observedAttributesIterable be Get(constructor, "observedAttributes"). 例外を再度投げる。

      2. If observedAttributesIterable is not undefined, then set observedAttributes to the result of converting observedAttributesIterable to a sequence<DOMString>. Rethrow any exceptions from the conversion.

    Then, perform the following substep, regardless of whether the above steps threw an exception or not:

    1. Unset this CustomElementRegistry's element definition is running flag.

    Finally, if the first set of substeps threw an exception, then rethrow that exception, and terminate this algorithm. Otherwise, continue onward.

  11. Let definition be a new custom element definition with name name, local name localName, constructor constructor, observed attributes observedAttributes, and lifecycle callbacks lifecycleCallbacks.

  12. Add definition to this CustomElementRegistry.

  13. Let document be this CustomElementRegistry's relevant global object's associated Document.

  14. Let upgrade candidates be all elements that are shadow-including descendants of document, whose namespace is the HTML namespace and whose local name is localName, in shadow-including tree order. Additionally, if extends is non-null, only include elements whose is value is equal to name.

  15. For each element element in upgrade candidates, enqueue a custom element upgrade reaction given element and definition.

  16. If this CustomElementRegistry's when-defined promise map contains an entry with key name:

    1. Let promise be the value of that entry.

    2. Resolve promise with undefined.

    3. Delete the entry with key name from this CustomElementRegistry's when-defined promise map.

When invoked, the get(name) method must run these steps:

  1. If this CustomElementRegistry contains an entry with name name, then return that entry's constructor.

  2. Otherwise, return undefined.

When invoked, the whenDefined(name) method must run these steps:

  1. If name is not a valid custom element name, then return a new promise rejected with a "SyntaxError" DOMException and abort these steps.

  2. If this CustomElementRegistry contains an entry with name name, then return a new promise resolved with undefined and abort these steps.

  3. Let map be this CustomElementRegistry's when-defined promise map.

  4. If map does not contain an entry with key name, create an entry in map with key name and whose value is a new promise.

  5. Let promise be the value of the entry in map with key name.

  6. Return promise.

The whenDefined() method can be used to avoid performing an action until all appropriate custom elements are defined. In this example, we combine it with the :defined pseudo-class to hide a dynamically-loaded article's contents until we're sure that all of the autonomous custom elements it uses are defined.

articleContainer.hidden = true;

fetch(articleURL)
  .then(response => response.text())
  .then(text => {
    articleContainer.innerHTML = text;

    return Promise.all(
      [...articleContainer.querySelectorAll(":not(:defined)")]
        .map(el => customElements.whenDefined(el.localName))
    );
  })
  .then(() => {
    articleContainer.hidden = false;
  });

4.13.5 Upgrades

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

  1. If element is custom, abort these steps.

    This can occur due to reentrant invocation of this algorithm, as in the following example:

    <!DOCTYPE html>
    <x-foo id="a"></x-foo>
    <x-foo id="b"></x-foo>
    
    <script>
    // Defining enqueues upgrade reactions for both "a" and "b"
    customElements.define("x-foo", class extends HTMLElement {
      constructor() {
        super();
    
        const b = document.querySelector("#b");
        b.remove();
    
        // While this constructor is running for "a", "b" is still
        // undefined, and so inserting it into the document will enqueue a
        // second upgrade reaction for "b" in addition to the one enqueued
        // by defining x-foo.
        document.body.appendChild(b);
      }
    })
    </script>

    This step will thus bail out the algorithm early when upgrade an element is invoked with "b" a second time.

  2. If element's custom element state is "failed", then abort these steps.

  3. 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.

  4. If element is connected, then enqueue a custom element callback reaction with element, callback name "connectedCallback", and an empty argument list.

  5. Add element to the end of definition's construction stack.

  6. Let C be definition's constructor.

  7. Run the following substeps while catching any exceptions:

    1. Let constructResult be the result of constructing C, with no arguments.

      If C non-conformantly uses an API decorated with the [CEReactions] extended attribute, then the reactions enqueued at the beginning of this algorithm will execute during this step, before C finishes and control returns to this algorithm. Otherwise, they will execute after C and the rest of the upgrade process finishes.

    2. If SameValue(constructResult, element) is false, then throw an "InvalidStateError" DOMException.

      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.

    Then, perform the following substep, regardless of whether the above steps threw an exception or not:

    1. Remove the last entry from the end of definition's construction stack.

      Assuming C calls super() (as it will if it is conformant), and that the call succeeds, this will be the already constructed marker that replaced the element we pushed at the beginning of this algorithm. (The HTML element constructor carries out this replacement.)

      If C does not call super() (i.e. it is not conformant), or if any step in the HTML element constructor throws, then this entry will still be element.

    Finally, if the above steps threw an exception, then:

    1. Set element's custom element state to "failed".

    2. Empty element's custom element reaction queue.

    3. Rethrow the exception, and terminate this algorithm.

  8. Set element's custom element state to "custom".

  9. Set element's custom element definition to definition.

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

  1. Let definition be the result of looking up a custom element definition given element's node document, element's namespace, element's local name, and element's is value.

  2. If definition is not null, then enqueue a custom element upgrade reaction given element and definition.

4.13.6 Custom element reactions

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

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. The current element queue is the element queue at the top of the custom element reactions stack. Each item in the stack is an element queue, which is initially empty as well. 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.)

Each custom element reactions stack has an associated backup element queue, which an initially-empty element queue. Elements are pushed onto the backup element queue during operations that affect the DOM without going through an API decorated with [CEReactions], or through the parser's create an element for the token algorithm. An example of this is a user-initiated editing operation which modifies the descendants or attributes of an editable element. To prevent reentrancy when processing the backup element queue, each custom element reactions stack also has a processing the backup element queue flag, initially unset.

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:

これは、次の模式図にすべて要約される:

A custom element reactions stack consists of a stack of element queues. Zooming in on a particular queue, we see that it contains a number of elements (in our example, <x-a>, then <x-b>, then <x-c>). Any particular element in the queue then has a custom element reaction queue. Zooming in on the custom element reaction queue, we see that it contains a variety of queued-up reactions (in our example, upgrade, then attribute changed, then another attribute changed, then connected).

To enqueue an element on the appropriate element queue, given an element element, run the following steps:

  1. If the custom element reactions stack is empty, then:

    1. Add element to the backup element queue.

    2. If the processing the backup element queue flag is set, abort this algorithm.

    3. Set the processing the backup element queue flag.

    4. Queue a microtask to perform the following steps:

      1. Invoke custom element reactions in the backup element queue.

      2. Unset the processing the backup element queue flag.

  2. Otherwise, add element to the current element queue.

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 definition be element's custom element definition.

  2. Let callback be the value of the entry in definition's lifecycle callbacks with key callbackName.

  3. If callback is null, then abort these steps.

  4. If callbackName is "attributeChangedCallback", then:

    1. Let attributeName be the first element of args.

    2. If definition's observed attributes does not contain attributeName, then abort these steps.

  5. Add a new callback reaction to element's custom element reaction queue, with callback function callback and arguments args.

  6. Enqueue an element on the appropriate element queue given element.

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. Enqueue an element on the appropriate element queue given element.

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 an exception, catch it, and report the exception.


To ensure custom element reactions are triggered appropriately, we introduce the [CEReactions] IDL extended attribute. It indicates that the relevant algorithm is to be supplemented with additional steps in order to appropriately track and invoke custom element reactions.

The [CEReactions] extended attribute must take no arguments, and must not appear on anything other than an operation, attribute, setter, or deleter. Additionally, it must not appear on readonly attributes.

Operations, attributes, setters, or deleters annotated with the [CEReactions] extended attribute must run the following steps surrounding the actions listed in the description of the operation, setter, deleter, or the attribute's setter:

Before executing the listed actions
Push a new element queue onto the custom element reactions stack.
After executing the listed actions
Pop the element queue from the custom element reactions stack, and invoke custom element reactions in that queue.

The intent behind this extended attribute is somewhat subtle. One way of accomplishing its goals would be to say that every operation, attribute, setter, and deleter on the platform must have these steps inserted, and to allow implementers to optimize away unnecessary cases (where no DOM mutation is possible that could cause custom element reactions to occur).

However, in practice this imprecision could lead to non-interoperable implementations of custom element reactions, as some implementations might forget to invoke these steps in some cases. Instead, we settled on the approach of explicitly annotating all relevant IDL constructs, as a way of ensuring interoperable behavior and helping implementations easily pinpoint all cases where these steps are necessary.

Any nonstandard APIs introduced by the user agent that could modify the DOM in such a way as to cause enqueuing a custom element callback reaction or enqueuing a custom element upgrade reaction, for example by modifying any attributes or child elements, must also be decorated with the [CEReactions] attribute.

As of the time of this writing, the following nonstandard or not-yet-standardized APIs are known to fall into this category: