Componentes Web: Construye Componentes de UI Reutilizables con JavaScript Vanilla
Aprende Componentes Web paso a paso construyendo una tarjeta de UI reutilizable con Custom Elements, Shadow DOM, HTML Templates, slots y módulos de JavaScript. No se requiere framework ni herramientas de construcción.
Web Components: Construye componentes de IU reutilizables con JavaScript puro
Imagina crear una tarjeta para tu sitio web y luego usarla en un tema de WordPress, una extensión de Joomla o una aplicación independiente sin reescribirla para cada entorno.
Esa es la promesa de Web Components: herramientas nativas del navegador para crear elementos HTML reutilizables. No se requiere React, Vue, paquetes de npm ni empaquetador para el ejemplo que vamos a construir.
Al final de este tutorial, tendrás un componente <ui-card> funcional con contenido personalizable, estilos aislados, una variante destacada, un botón de descarte y un evento público. Lo construiremos en pasos pequeños para que puedas ver qué aporta cada tecnología.
Lo que construirás
Nuestro componente terminado admitirá este HTML:
<ui-card variant="featured">
<span slot="title">Learn Web Components</span>
<p>Build reusable interfaces with native JavaScript.</p>
<a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>
Vista previa visual — tarjetas estándar y destacadas
<div style="padding:16px;border:1px solid #dce3ec;border-radius:14px;background:#f8fafc;margin:16px 0"> <div style="padding:20px;border:1px solid #dce3ec;border-radius:12px;background:#fff;margin-bottom:12px"> <strong style="display:block;margin-bottom:6px">Tarjeta estándar</strong> <span>Esta tarjeta usa la apariencia predeterminada.</span> </div> <div style="padding:20px;border:1px solid #93c5fd;border-radius:12px;background:#eff6ff"> <strong style="display:block;color:#1d4ed8;margin-bottom:6px">Tarjeta destacada</strong> <span>Esta tarjeta tiene una apariencia resaltada.</span> </div> </div>
Esta vista previa es el objetivo de diseño, no una captura de pantalla de una biblioteca no relacionada. La reproduciremos usando el código a continuación.
1. Comprender los cuatro bloques de construcción
Custom Elements nos permiten registrar una nueva etiqueta HTML y su comportamiento de JavaScript. Shadow DOM le da al elemento su propio DOM interno y estilos con alcance. HTML templates and slots nos permiten reutilizar la estructura mientras insertamos diferentes contenido en cada instancia. ES Modules nos permiten cargar el componente desde un archivo JavaScript normal.
Estas son características separadas. Un Custom Element no tiene que usar Shadow DOM, y no necesitas un framework para usar ninguna de ellas.
2. Crear los archivos del proyecto
Crea esta estructura en tu editor:
web-components-demo/
├── index.html
├── components/
│ └── ui-card.js
└── css/
└── main.css
Pon esto en index.html:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Web Components Demo</title>
<link rel="stylesheet" href="./css/main.css">
<script type="module" src="./components/ui-card.js"></script>
</head>
<body>
<main class="container">
<h1>Reusable UI Components</h1>
<p>Let's build a reusable card without a framework.</p>
<ui-card></ui-card>
</main>
</body>
</html>
Agrega los estilos a nivel de página a css/main.css:
body {
margin: 0;
background: #f4f6f9;
color: #1f2937;
font-family: system-ui, sans-serif;
}
.container {
max-width: 900px;
margin: 60px auto;
padding: 0 20px;
}
ui-card {
display: block;
margin-top: 24px;
}
Ejecuta un servidor HTTP local desde el directorio del proyecto, por ejemplo:
python -m http.server 8000
Visita http://localhost:8000. Aparece el título, pero la tarjeta no tiene contenido visible todavía. Usa un servidor HTTP en lugar de abrir index.html con file://: las reglas de carga de módulos del navegador pueden bloquear las importaciones de archivos locales.
3. Registrar tu primer Custom Element
Crea components/ui-card.js:
class UiCard extends HTMLElement {
connectedCallback() {
this.textContent = 'Hello from a Web Component!';
}
}
customElements.define('ui-card', UiCard);
Actualiza la página. Ahora deberías ver:
Resultado esperado — Paso 3
¡Hola desde un Web Component!
HTMLElement proporciona comportamiento DOM normal. connectedCallback() se ejecuta cuando el elemento se conecta al documento. customElements.define() asocia la clase con la etiqueta HTML.
El guion en ui-card es obligatorio para los nombres de Custom Element autónomos. La devolución de llamada puede ejecutarse de nuevo si el elemento se desconecta y se vuelve a insertar, lo que importa cuando agregamos lógica de inicialización.
4. Darle a la tarjeta su propio diseño con Shadow DOM
Reemplaza ui-card.js con:
class UiCard extends HTMLElement {
connectedCallback() {
if (this.shadowRoot) return;
const shadow = this.attachShadow({ mode: 'open' });
shadow.innerHTML = `
<style>
article {
padding: 24px;
background: white;
border: 1px solid #dce3ec;
border-radius: 12px;
}
h2 {
margin: 0 0 12px;
color: #2563eb;
}
</style>
<article>
<h2>My reusable card</h2>
<p>This content lives inside Shadow DOM.</p>
</article>
`;
}
}
customElements.define('ui-card', UiCard);
Resultado esperado — Paso 4
<div style="padding:22px;border:1px solid #dce3ec;border-radius:12px;background:#fff;margin:16px 0"> <strong style="display:block;color:#2563eb;font-size:20px;margin-bottom:10px">Mi tarjeta reutilizable</strong> Este contenido vive dentro de Shadow DOM. </div>
Abre las Herramientas para desarrolladores, inspecciona <ui-card> y expande #shadow-root (open). Verás el artículo interno y la hoja de estilos.
A diferencia de los selectores de documento ordinarios, el CSS global como article { border: none } normalmente no alcanza este árbol shadow. Las propiedades heredadas y las propiedades personalizadas de CSS aún pueden cruzar el límite. Shadow DOM encapsula la presentación; no es un sandbox de seguridad.
La protección if (this.shadowRoot) evita adjuntar una segunda raíz shadow si el elemento se reconecta.

5. Separar el diseño con una plantilla HTML
Insertar todo dentro de connectedCallback() resulta incómodo a medida que un componente crece. Definamos el marcado una vez y clonémoslo para cada tarjeta.
Reemplaza el archivo con:
const template = document.createElement('template');
template.innerHTML = `
<style>
article {
padding: 24px;
background: white;
border: 1px solid #dce3ec;
border-radius: 12px;
}
h2 {
margin: 0 0 12px;
color: #2563eb;
}
</style>
<article>
<h2>My reusable card</h2>
<p>Created from an HTML template.</p>
</article>
`;
class UiCard extends HTMLElement {
connectedCallback() {
if (this.shadowRoot) return;
const shadow = this.attachShadow({ mode: 'open' });
shadow.appendChild(template.content.cloneNode(true));
}
}
customElements.define('ui-card', UiCard);
template.content es un fragmento de documento. cloneNode(true) copia toda la estructura en el árbol shadow de cada tarjeta. La plantilla en sí no se renderiza hasta que la clonamos e insertamos.
Esta versión se ve casi idéntica. La mejora es arquitectónica: una plantilla puede servir para muchas instancias.
6. Insertar contenido diferente usando ranuras
Una tarjeta reutilizable no es útil si cada instancia tiene el mismo título. Reemplaza solo la declaración de plantilla en la parte superior de ui-card.js con lo siguiente; mantén el código de clase y registro del Paso 5.
const template = document.createElement('template');
template.innerHTML = `
<style>
article {
padding: 24px;
background: white;
border: 1px solid #dce3ec;
border-radius: 12px;
}
h2 { margin: 0 0 12px; color: #2563eb; }
.content { line-height: 1.6; }
.action { margin-top: 16px; }
</style>
<article>
<h2><slot name="title">Untitled card</slot></h2>
<div class="content"><slot></slot></div>
<div class="action"><slot name="action"></slot></div>
</article>
`;
Ahora reemplaza <ui-card></ui-card> en index.html:
<ui-card>
<span slot="title">Learn Web Components</span>
<p>Build reusable interfaces with native JavaScript.</p>
<a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>
Resultado esperado — Paso 6
<div style="padding:22px;border:1px solid #dce3ec;border-radius:12px;background:#fff;margin:16px 0"> <strong style="display:block;color:#2563eb;font-size:20px;margin-bottom:10px">Aprende Web Components</strong> <p style="margin:0 0 12px">Crea interfaces reutilizables con JavaScript nativo.</p> <span style="color:#2563eb;font-weight:600">Lee el tutorial</span> </div>
La ranura nombrada recibe el elemento marcado slot="title". La ranura sin nombre recibe el párrafo. La ranura de acción recibe el enlace. El texto de reserva de una ranura aparece si no se le asigna nada.
El diseño vive en el componente; las palabras y enlaces reales permanecen en el HTML de la página. Esto es especialmente útil para el contenido de CMS. Reemplaza /tutorial con un destino real en tu proyecto.
7. Crear una variante destacada con CSS
Dentro del bloque <style> de la plantilla, agrega:
:host {
display: block;
}
:host([variant="featured"]) article {
background: #eff6ff;
border-color: #93c5fd;
}
Luego reemplaza la tarjeta única en index.html con dos tarjetas:
<ui-card>
<span slot="title">Standard card</span>
<p>This card uses the default appearance.</p>
</ui-card>
<ui-card variant="featured">
<span slot="title">Featured card</span>
<p>This card has a highlighted appearance.</p>
</ui-card>
Resultado esperado — Paso 7
<div style="padding:12px;border:1px solid #e2e8f0;border-radius:14px;background:#fafafa;margin:16px 0"> <div style="padding:18px;border:1px solid #dce3ec;border-radius:12px;background:white;margin-bottom:12px"> <strong style="display:block;margin-bottom:6px">Tarjeta estándar</strong> Esta tarjeta usa la apariencia predeterminada. </div> <div style="padding:18px;border:1px solid #93c5fd;border-radius:12px;background:#eff6ff"> <strong style="display:block;color:#1d4ed8;margin-bottom:6px">Tarjeta destacada</strong> Esta tarjeta tiene una apariencia resaltada. </div> </div>
Esta es una característica particularmente útil de :host(): estiliza el componente según los atributos del elemento personalizado. Si JavaScript cambia variant más tarde, el CSS se actualiza automáticamente. No se necesita attributeChangedCallback() para un cambio puramente impulsado por CSS.
8. Agregar un botón de descarte y un evento público
Hagamos que la tarjeta sea interactiva. Dentro del bloque <article> de la plantilla, agrega este botón antes del título:
<button class="dismiss" type="button" aria-label="Dismiss card">
×
</button>
Agrega estas reglas al CSS de la plantilla:
article { position: relative; }
.dismiss {
position: absolute;
top: 12px;
right: 12px;
width: 32px;
height: 32px;
border: 0;
border-radius: 6px;
background: transparent;
color: #475569;
font-size: 24px;
cursor: pointer;
}
.dismiss:focus-visible {
outline: 2px solid #2563eb;
outline-offset: 2px;
}
Reemplaza connectedCallback() en la clase con:
connectedCallback() {
if (this.shadowRoot) return;
const shadow = this.attachShadow({ mode: 'open' });
shadow.appendChild(template.content.cloneNode(true));
shadow.querySelector('.dismiss').addEventListener('click', () => {
this.dispatchEvent(new CustomEvent('card-dismissed', {
bubbles: true,
composed: true
}));
this.remove();
});
}
En index.html, agrega este script antes de </body>:
<script type="module">
document.addEventListener('card-dismissed', () => {
console.log('A card was dismissed.');
});
</script>
Abre la consola del navegador y haz clic en ×. La tarjeta desaparece y la consola muestra el mensaje.
El evento proporciona un punto de integración público: la aplicación circundante no necesita saber nada sobre el botón interno de la tarjeta. bubbles hace que el evento burbujee; composed permite cruzar un límite shadow cuando corresponde. Aquí el evento se origina en el elemento host mismo.
9. Versión final completa: copiar y usar

Ahora puedes reemplazar todo el contenido de components/ui-card.js con esta versión consolidada. Agrega personalización CSS y partes exportadas mientras conserva el comportamiento construido en pasos anteriores.
const template = document.createElement('template');
template.innerHTML = `
<style>
:host {
display: block;
color: #1f2937;
font-family: system-ui, sans-serif;
}
article {
position: relative;
box-sizing: border-box;
padding: 24px;
background: var(--card-background, #fff);
border: 1px solid var(--card-border, #dce3ec);
border-radius: 12px;
}
:host([variant="featured"]) article {
background: var(--card-featured-background, #eff6ff);
border-color: var(--card-featured-border, #93c5fd);
}
h2 {
margin: 0 36px 12px 0;
color: var(--card-title-color, #2563eb);
font-size: 1.25rem;
}
.content { line-height: 1.6; }
.action { margin-top: 16px; }
.dismiss {
position: absolute;
top: 12px;
right: 12px;
width: 32px;
height: 32px;
border: 0;
border-radius: 6px;
background: transparent;
color: #475569;
font-size: 24px;
cursor: pointer;
}
.dismiss:hover { background: rgba(0, 0, 0, 0.06); }
.dismiss:focus-visible {
outline: 2px solid #2563eb;
outline-offset: 2px;
}
</style>
<article part="container">
<button class="dismiss" type="button"
aria-label="Dismiss card">×</button>
<h2 part="title"><slot name="title">Untitled card</slot></h2>
<div class="content"><slot></slot></div>
<div class="action"><slot name="action"></slot></div>
</article>
`;
class UiCard extends HTMLElement {
connectedCallback() {
if (this.shadowRoot) return;
const shadow = this.attachShadow({ mode: 'open' });
shadow.appendChild(template.content.cloneNode(true));
shadow.querySelector('.dismiss').addEventListener('click', () => {
this.dispatchEvent(new CustomEvent('card-dismissed', {
bubbles: true,
composed: true,
detail: {
variant: this.getAttribute('variant') || 'default'
}
}));
this.remove();
});
}
}
if (!customElements.get('ui-card')) {
customElements.define('ui-card', UiCard);
}
A diferencia de una demostración rápida, esta versión no intenta adjuntar la raíz shadow dos veces, no inserta contenido no confiable con innerHTML, y no depende de un framework. La cadena de plantilla está controlada por el desarrollador; nunca interpoles entrada de usuario no confiable en ella.
10. Estilizarlo desde el sitio de alojamiento
Shadow DOM no pretende hacer imposible la personalización. Te anima a definir una interfaz de estilo intencional.
En css/main.css, agrega:
ui-card {
--card-border: #cbd5e1;
--card-title-color: #0f766e;
}
ui-card::part(container) {
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}
Las propiedades personalizadas son heredadas por el árbol shadow y controlan los valores que expusimos. El atributo part="container" permite que el CSS externo se dirija a un elemento interno seleccionado con ::part(container).
Si necesitas un fondo destacado diferente, usa --card-featured-background. Esto es preferible a obligar a los consumidores a depender de la estructura interna exacta del DOM.
11. Reutilizar la tarjeta en WordPress, Joomla o HTML sencillo
Copia ui-card.js en el sitio web de destino y cárgalo como un módulo de JavaScript:
<script type="module" src="/assets/js/ui-card.js"></script>
Luego usa <ui-card> en el marcado de la página. En WordPress, registra los recursos a través de las API de carga de scripts compatibles con el tema o complemento, usando soporte de módulos apropiado para tu versión de WordPress. En Joomla, usa el Web Asset Manager para registrar y cargar el módulo. No esparzas etiquetas de script codificadas a través de plantillas de producción.
Para una tarjeta generada por CMS, renderiza el título, el párrafo y el enlace como HTML en ranuras. Escapa el contenido y los atributos según las reglas de salida del CMS.
Beneficio práctico: un módulo de Joomla y un bloque de WordPress pueden generar la misma etiqueta personalizada mientras comparten una implementación de componente. Cada CMS sigue siendo responsable de obtener y escapar su propio contenido.
12. Accesibilidad, SEO y mejora progresiva
Usa controles HTML nativos dentro de los componentes siempre que sea posible. Nuestra acción de descarte usa un botón button real, que proporciona semántica de activación por teclado, y un aria-label porque × por sí solo no es descriptivo.
Si un usuario descarta una tarjeta con foco de teclado, considera a dónde debe ir el foco a continuación en una interfaz más compleja. Los diálogos, menús y cuadros combinados necesitan mucho más comportamiento de accesibilidad que este ejemplo.
Mantén el contenido importante en marcado de luz-DOM significativo cuando sea práctico. Si JavaScript falla, el navegador no actualizará <ui-card>; el título y el párrafo en ranura permanecen en el documento, aunque el cascarón con estilo del componente y el botón de descarte no existirán.
Para los motores de búsqueda, no asumas que el contenido solo de JavaScript se indexa de manera idéntica en todos los rastreadores. El contenido crítico debe estar disponible en el HTML inicial o a través de una estrategia de renderizado adecuada.
Shadow DOM también tiene limitaciones: los selectores CSS de documento ordinarios no dan estilo a los nodos internos, y algunas relaciones de ID de ARIA no pueden cruzar los límites shadow. Diseña las API de los componentes con esas restricciones en mente.
13. ¿Los Web Components siempre son más rápidos?
No necesariamente. Los Web Components evitan requerir un runtime de framework en particular, pero el rendimiento depende de la cantidad de JavaScript, la complejidad del DOM, la frecuencia de renderizado y la arquitectura de la aplicación.
Una tarjeta pequeña es una buena candidata. Cientos de elementos complejos con reconstrucción de DOM innecesaria aún pueden ser lentos. Reutiliza plantillas, evita renderizados completos repetidos y mide el rendimiento real.
Para una aplicación grande ya construida alrededor de la gestión de estado y el enrutamiento de un framework, usar los propios componentes de ese framework puede ser más simple. Los Web Components brillan cuando un elemento de IU estable necesita cruzar límites de framework o CMS.
14. Solución de problemas
| Síntoma | Causa probable | Qué verificar |
|---|---|---|
| La tarjeta está vacía | El módulo no cargó | Consola de Herramientas para desarrolladores, URL, tipo MIME del servidor |
customElements.define arroja |
Nombre inválido o duplicado | Requisito de guion y protección de registro |
| El CSS no se aplica dentro de la tarjeta | Límite de Shadow DOM | Usa propiedades personalizadas, :host o ::part |
| El contenido aparece en el lugar incorrecto | Nombre de ranura incorrecto | Compara slot="title" con <slot name="title"> |
| Hacer clic en descartar no hace nada | Falta el botón de plantilla | Inspecciona el árbol shadow y la consola |
| El componente falla al moverse | La inicialización se ejecuta dos veces | Protege la creación de la raíz shadow |
| El enlace lleva a 404 | La URL de ejemplo no se reemplazó | Usa un destino existente |
Recuerda que connectedCallback() puede ejecutarse más de una vez. La protección en nuestro ejemplo final mantiene la inicialización como única; componentes más sofisticados pueden necesitar adjuntar y eliminar observadores externos o oyentes de eventos globales durante su ciclo de vida de conexión.
15. ¿Cuándo deberías usar Web Components?
Elígelos cuando un componente necesite una interfaz HTML reutilizable y documentada en varios sitios web, frameworks o entornos de CMS. Tarjetas, notificaciones, widgets de productos y pequeñas herramientas interactivas son buenos candidatos.
Omite la abstracción cuando unas pocas líneas de HTML y CSS ordinarios ya resuelven el problema. Y no recrees controles nativos sin una razón sólida.
Una prueba útil: ¿se beneficiaría otra aplicación de usar este elemento sin saber cómo se implementó? Si la respuesta es sí, un Web Component vale la pena considerarlo.
Conclusión
Has construido un componente reutilizable real, no solo leído sobre una API del navegador. Tiene una etiqueta personalizada, estilos con alcance, contenido configurable, una variante destacada y un evento al que otro código puede escuchar.
Comienza con un componente que aparezca repetidamente en tus proyectos. Dale una pequeña API pública, pruébalo en más de un diseño y mantén sus dependencias mínimas.
El valor a largo plazo de los Web Components no es que reemplacen a todos los frameworks. Es que permiten que los elementos de interfaz útiles sobrevivan al framework o CMS que los alojó por primera vez.