This document describes how custom elements v1 work when they are defined or used in HTML Imports.
HTML Imports is currently implemented only in Chrome, and this document provides non-normative information about Chrome's implementation in M54 and later, for the reference of future works that tries to achieve similar functionality like HTML Imports.
As the global context window is shared with script running in an imported document, you can access the custom elements registry via window.customElements. This is straightforward and no different from the usage in a usual HTML document.
Imported HTML:
<!DOCTYPE html>
<script>
class MyElement extends HTMLElement {}
window.customElements.define('my-element', MyElement);
</script>After the definition is registered, new MyElement() will work in any <script>. Any custom element created via new operator will have the master document (i.e. window.document) as its node document (.ownerDocument), regardless of where the new operator is invoked.
When you put a custom element tag (e.g. <my-element>...</my-element>), depending on whether the definition is available in the registry, it is created synchronously as parsed, or upgraded when the definition is registered.
On either case node document of each custom element will be the containing imported document.
When you use createElement() API to create a custom element, you can use the master document or any imported document as the context object. Created element will have the context object of createElement() as its .ownerDocument.
Putting custom elements in .innerHTML works in script running in imported document. Its node document will be inherited from .innerHTML's context object.
Each definition will be available immediately after customElements.define() call, therefore the availability depends on the order of script execution in HTML imports.
The upgrade order of custom elements follows custom element order defined in HTML Imports spec.
In short, upgrade also happens for imported documents that are completely loaded, and the order is document order, where all <link rel="import"> elements are replaced with imported document.
Even when an import is async, upgrade can apply to elements in an asynchrnonously imported document, the order is same without async attribute.
If an import is detached before definition is given, custom elements in the detached imported document will not be upgraded when the definition becomes available. If already upgraded custom elements exist when an imported document is being detached, they keep the same state (custom) after the detachment.
When you move an element from an import to the master (or vice versa), adoptedCallback() for the element will be run.
You can expect attributeChangedCallback() for the element will be run in imports.
As imports are Documents, when custom elements are created or upgraded in an import's DOM tree, connectedCallback() will be run.