CKTIS / JavaScript
customElements.define — registrar un elemento personalizado
customElements.define asocia el nombre de un elemento con un constructor en el registro del documento. Aprende la diferencia entre los elementos personalizados autónomos y los elementos integrados personalizados, además de las principales restricciones de registro.
Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxis
customElements.define(name, constructor);
customElements.define(name, constructor, { extends: baseLocalName });customElements.define(name, constructor, options) registra una definición en el registro disponible mediante window.customElements y devuelve undefined, no una instancia ni una promesa. Esta es una API del HTML Living Standard, no una característica de una edición concreta de ECMAScript. Los elementos personalizados autónomos son compatibles con los motores de navegador modernos; que Node 24 esté en un repositorio no demuestra que esta API esté disponible.
Un elemento autónomo usa una clase que extiende HTMLElement. Un nombre válido sencillo, como cktis-greeting, empieza por una letra ASCII minúscula, contiene un guion y no contiene letras ASCII mayúsculas; algunos nombres también están reservados. El registro permite crear instancias y actualizar los elementos coincidentes que ya estén en el documento. Por sí solo, no inserta un elemento nuevo en el DOM.
La variante { extends: "button" } define un elemento integrado personalizado: su clase extiende HTMLButtonElement, y se crea una instancia con document.createElement("button", { is: name }), no con document.createElement(name). Comprueba por separado la compatibilidad de esta variante en los navegadores de destino.
Un nombre no válido provoca SyntaxError, mientras que reutilizar un nombre o un constructor en el mismo registro provoca NotSupportedError; ambos son excepciones DOMException. Un argumento que no sea un constructor provoca TypeError. El ejemplo establece el contenido en connectedCallback, después de añadir el elemento; no añadas hijos ni atributos en el constructor. Vuelve a cargar el documento antes de ejecutarlo otra vez: eliminar una instancia no elimina su definición.
Ejemplos
(() => {
class CktisGreeting extends HTMLElement {
connectedCallback() {
this.textContent = "Hello!";
}
}
customElements.define("cktis-greeting", CktisGreeting);
const element = document.createElement("cktis-greeting");
document.body.append(element);
console.log(element.textContent);
console.log(element instanceof CktisGreeting);
element.remove();
})();Resultado
Hello! true
El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.