Custom Element Conventions

Whenever possible custom elements are defined each in their own ES module
- The file name should match the element tag name, so <my-element> is in my-element.mjs
- The class name should match the custom element tag name, just in PascalCase.
- The custom element registers itself in the customElements registry at the end of the file. For example
```
  customElements.define("my-element", MyElement);
```
- If the element should be extended by other elements, it should be exported as a named export in the module.
Any other custom elements the element depends on or uses in its template should be imported in the element’s module.
External features of the custom element (attributes, slots, parts, css custom properties, events etc.) are documented using these jsdoc tags: https://custom-elements-manifest.open-wc.org/analyzer/getting-started/#supported-jsdoc
For events the handleEvents method callback should be used, and just the this reference is passed to addEventListener. See https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#the_event_listener_callback
- This also lets us modify event handling through inheritance.
- Any events attached to elements that aren’t within the custom element need to be removed in the disconnectedCallback (and should be registered again if the element gets re-attached).
If the element doesn’t attach a shadow root in its connectedCallback, consider using a hasConnected class field to detect if the main setup logic has already happened.
Templates are currently managed in HTML markup and we just document the ID of the template that the custom element expects as Template ID: #myElementTemplate. Often the template is in an include file we include anywhere the custom element is used.
Styles for the custom element are usually in a separate css file with the same name as the module. If the element has a shadow root, the stylesheet will be loaded into it.
When interacting with other custom elements, you should follow these methods:
- To send (or request) information to a child element, call a method on it.
- To send information to a parent element (without the parent requesting it in a method call), emit the information in a custom event.
If the state needs to be updated from a parent with an explicit function call, consider using an initialize method that is also called from the connectedCallback.
XPCOM Observers registered with the nsIObserverService should generally be weak observers. This is safe, because the custom element (and thus the observer) will usually be owned by a DOM scope. The observing element needs to explicitly declare the nsISupportsWeakReference and nsIObserver interfaces in the QueryInterface method. The observer should of course also be unregistered in the disconnectedCallback.
Unless key repeats are desired, consider using keyup listeners for keyboard event handling.

Custom Element Boilerplate

my-element.mjs

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, you can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 * Example component serving as a boilerplate demonstration.
 * You should never see this description in the wild.
 * Template ID: #myElementTemplate
 *
 * @attribute {string} label - Label of the button. Observed for changes.
 * @tagname my-element
 */
export class MyElement extends HTMLElement {
  static get observedAttributes() {
    return ["label"];
  }

  QueryInterface = ChromeUtils.generateQI([
    "nsIObserver",
    "nsISupportsWeakReference"
  ]);

  connectedCallback() {
    window.addEventListener("resize", this);
    Services.obs.addObserver(this, "some-topic", true);

    if (this.shadowRoot) {
      return;
    }

    const shadowRoot = this.attachShadow({ mode: "open" });
    const styles = document.createElement("link");
    styles.rel = "stylesheet";
    styles.href = "chrome://messenger/skin/shared/my-element.css";
    const template = document
      .getElementById("myElementTemplate")
      .content.cloneNode(true);

    template.querySelector("button").addEventListener("click", this);
    template.querySelector("button").textContent = this.getAttribute("label");

    shadowRoot.append(styles, template);

    document.l10n.connectRoot(shadowRoot);
  }

  disconnectedCallback() {
    window.removeEventListener("resize", this);
    Services.obs.removeObserver(this, "some-topic");
    document.l10n.disconnectRoot(this.shadowRoot);
  }

  attributeChangedCallback(attribute) {
    switch (attribute) {
      case "label":
        this.shadowRoot.querySelector("button").textContent = this.getAttribute("label");
        break;
    }
  }

  handleEvent(event) {
    switch (event.type) {
      case "click":
        console.log("clicked!");
        break;
      case "resize":
        console.warn("Why would you want a resize listener?");
        break;
    }
  }

  observe(subject, topic, data) {
    switch(topic) {
      case "some-topic":
        console.log("observer notification");
        break;
    }
  }
}
customElements.define("my-element", MyElement);

myElementTemplate.inc.xhtml

<template id="myElementTemplate">
  <span data-l10n-id="my-element-string"></span>
  <button class="button" data-l10n-id="my-element-button"></button>
</template>

Loading Custom Elements

If the template of a custom element relies on another custom element, we will generally directly import that other custom element at the top of the module with a synchronous import statement:

import "chrome://messenger/content/other-element.mjs"; // eslint-disable-line import/no-unassigned-import

If we’re dynamically instantiating a custom element, if we can control it only happening once consider either using an import() call, ChromeUtils.importESModule or ChromeUtils.defineESModuleGetters() to only load the module when used:

async function createElementWithImport() {
  if (hasElement) {
    return;
  }
  await import("chrome://messenger/content/other-element.mjs");
  document.createElement("other-element");
}

function createElementSynchronously() {
  if (hasElement) {
    return;
  }
  ChromeUtils.importESModule(
    "chrome://messenger/content/other-element.mjs",
    { global: "current" }
  );
  document.createElement("other-element");
}

const lazy = {};
ChromeUtils.defineESModuleGetters(
  lazy,
  { OtherElement: "chrome://messenger/content/other-element.mjs" },
  { global: "current" }
);

function createLazyConstructedElement() {
  new lazy.OtherElement();
}

Yet another option is to use defineLazyCustomElement from chrome://messenger/content/CustomElementUtils.mjs. It is useful in situations where the previous options are hard to use.

defineLazyCustomElement(
  "other-element",
  "chrome://messenger/content/other-element.mjs"
);

function createLazyElement() {
  document.createElement("other-element");
}