Haz que los elementos personalizados se comporten con registros de alcance

Jayson Chen

Patrick Brosset

Publicado: 9 de marzo de 2026

Los elementos personalizados permiten que los desarrolladores de apps web compilen, compartan y reutilicen componentes de IU con sus comportamientos únicos, lo que facilita el desarrollo. Sin embargo, cuando tu app reúne diferentes conjuntos de elementos personalizados, las cosas pueden complicarse y pueden producirse colisiones de nombres. Los registros de elementos personalizados con alcance resuelven este problema.

El equipo de Microsoft Edge trabajó en esta función y nos complace anunciar que los registros de elementos personalizados con alcance ahora están disponibles de forma predeterminada en Edge y Chrome 146, así como en otros navegadores basados en Chromium. Ahora puedes encapsular elementos personalizados, lo que resuelve un problema que los desarrolladores de componentes y bibliotecas de microfrontends tenían desde hace mucho tiempo.

Los registros de elementos personalizados con alcance desbloquean patrones importantes para los desarrolladores web. Ahora, puedes usar varias bibliotecas de elementos personalizados, desarrolladas de forma independiente por varios equipos, o varias versiones de la misma biblioteca en paralelo.

¿Qué es un registro de elementos personalizados con alcance?

Actualmente, cada definición de elemento personalizado en una página web se encuentra en un registro compartido único en window.customElements. Esto significa que, si dos bibliotecas diferentes intentan definir un elemento personalizado con el mismo nombre de etiqueta, como <my-button>, se arrojará un error y la página dejará de funcionar. Este es un problema importante en el mundo real. Las aplicaciones grandes que componen sus interfaces de usuario a partir de varios equipos, sistemas de diseño o microfrontends pueden tener fácilmente conflictos de nombres. Los registros de elementos personalizados con alcance resuelven este problema, ya que te permiten crear registros independientes. Cada registro mantiene su propio conjunto de definiciones de elementos personalizados, completamente aislado del registro global y entre sí.

Crea un registro nuevo

En lugar de definir cada elemento personalizado en el registro global window.customElements, haz lo siguiente:

1. Llama a new CustomElementRegistry() para crear un registro nuevo.
2. Asigna a tu nuevo registro un alcance específico (consulta Cómo definir el alcance de tu registro).
3. Define los elementos que se incluirán en el nuevo registro.

Luego, cuando se usa un elemento personalizado, el navegador busca la definición del elemento en el registro asociado, que no necesariamente es el global. Esto significa que diferentes partes de tu página pueden usar conjuntos completamente diferentes de definiciones de elementos personalizados.

Limita el alcance de tu registro

Un registro de elementos personalizados puede tener un alcance limitado a un documento, una raíz de sombra o un elemento individual.

Cómo definir el alcance de una raíz de sombra

Para definir el alcance de un registro nuevo en una raíz de sombra, usa la opción customElementRegistry cuando llames al método attachShadow(). Todos los elementos personalizados que se encuentran dentro de esa raíz de sombra ahora usarán la definición que se encuentra en el registro con alcance correspondiente:

// Create your custom registry.
const registry = new CustomElementRegistry();
// Define a custom element in the new registry.
registry.define('my-card', class extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from scoped registry!';
  }
});

// Create shadow root, providing it with your new custom element registry.
const host = document.querySelector('#host');
const shadow = host.attachShadow({
  mode: 'open',
  customElementRegistry: registry,
});

shadow.innerHTML = '<my-card></my-card>';

Shadow DOM declarativo

Usa el atributo shadowrootcustomelementregistry en un elemento <template> para indicarle al navegador que la raíz de sombra resultante usa un registro con alcance en lugar del global:

<my-host>
  <template shadowrootmode="open" shadowrootcustomelementregistry>
    <my-widget></my-widget>
  </template>
</my-host>

  const registry = new CustomElementRegistry();
  registry.define('my-widget', class extends HTMLElement {
    connectedCallback() { this.textContent = 'Scoped!'; }
  });

  const shadow = document.querySelector('my-host').shadowRoot;
  registry.initialize(shadow);

Como se muestra en el ejemplo, el atributo reserva espacio para el registro de elementos personalizados, y el usuario debe definir e inicializar el registro en el alcance de la raíz de sombra en un documento desconectado.

También puedes definir el alcance de un registro para un documento, como uno creado por document.implementation.createHTMLDocument(). Esto te permite clonar elementos <template> y manipular documentos fuera de la pantalla, cada uno con sus propios conjuntos aislados de definiciones de componentes. Para ello, usa el método CustomElementRegistry.initialize():

// Create a new registry.
const registry = new CustomElementRegistry();
registry.define('app-widget', AppWidget);

// Create a document, and use registry.initialize() to scope the registry to the document.
const doc = document.implementation.createHTMLDocument('');
registry.initialize(doc);

doc.body.innerHTML = '<app-widget></app-widget>';

Cómo definir el alcance para un elemento individual

También puedes asociar un registro directamente con un elemento y su subárbol pasando la opción customElementRegistry a document.createElement(). El elemento y sus descendientes se resolverán en función de ese registro, sin importar en qué parte del DOM se inserten más adelante:

// Create a registry and define a custom element in it.
const registry = new CustomElementRegistry();
registry.define('fancy-label', FancyLabel);

// Create a new DOM element and scope the new registry to it.
const el = document.createElement('fancy-input', {
  customElementRegistry: registry,
});

// Use a custom element in the new DOM element.
el.innerHTML = '<fancy-label>Name</fancy-label>';

Más información

Para obtener más información, consulta la demostración de Edge y su código fuente, y lee el artículo de referencia de CustomElementRegistry de MDN.

Los registros de elementos personalizados con alcance ahora están habilitados de forma predeterminada en Microsoft Edge y Chrome, así como en otros navegadores basados en Chromium, gracias a nuestra colaboración a través del proyecto Chromium.

No es necesario que habilites ningún parámetro de configuración ni que te registres en una prueba de origen. Puedes comenzar a usar la función hoy mismo en los navegadores basados en Chromium.

Si necesitas que esta función se implemente en otros navegadores, reacciona con un me gusta al problema de los registros de elementos personalizados con alcance y deja un comentario con tus casos de uso y soluciones alternativas.

Si encuentras un error en la implementación de la función en un navegador basado en Chromium, abre un problema para que lo investiguemos en crbug.com/new.

Esperamos que los registros de elementos personalizados con alcance faciliten el uso de componentes web.