{"canonical_url":"https://engineer.company/es/glossary/web-components/","content_markdown":"# componentes web\n\n## Qué es\n\nLos componentes web, también llamados Web Components, son un conjunto de funciones\ndel navegador que permite definir elementos HTML propios. Una página usa después ese\nelemento como cualquier otra etiqueta. Los estándares nombran cada parte por separado:\nlos elementos personalizados y los elementos `template` y `slot` en HTML Standard, y\nlos árboles de sombra en DOM Standard. El nombre colectivo titula una nota de un grupo\nde trabajo del W3C de 24 de julio de 2014,\n[_Introduction to Web Components_](https://www.w3.org/TR/components-intro/),\nque el W3C dejó de mantener y marcó como documento que no debe citarse como referencia.\n\nUn elemento personalizado se define mediante una clase JavaScript que extiende\n`HTMLElement` y se registra con un nombre mediante `customElements.define()`. La\ndefinición indica al analizador HTML cómo construirlo y cómo debe reaccionar a los\ncambios. Desde ese momento puede crearse a partir del marcado, con\n`document.createElement()` o con `new`. Su nombre empieza por una letra ASCII minúscula,\nno contiene letras ASCII mayúsculas y debe contener un guion. El guion separa los\nnombres personalizados del propio lenguaje: HTML Standard establece que HTML, SVG y\nMathML no incorporarán ningún elemento cuyo nombre contenga un guion.\n\nHay dos tipos. Un elemento personalizado autónomo, como el ejemplo del estándar\n`\u003cflag-icon country=\"nl\"\u003e`, parte de un elemento sin significado incorporado. Un elemento\nintegrado personalizado extiende uno existente: una clase que extiende `HTMLButtonElement`,\nregistrada con `{ extends: \"button\" }` y usada como `\u003cbutton is=\"plastic-button\"\u003e`, conserva\ntodo lo que hace que un botón sea un botón, incluidos el comportamiento del foco,\nel envío de formularios y el atributo `disabled`.\n\nUn árbol de sombra es un árbol de nodos separado, unido a un elemento llamado anfitrión;\nDOM Standard llama árbol ligero al árbol normal del anfitrión. `attachShadow()` crea\nuna raíz de sombra en modo abierto o cerrado, y solo en el abierto la devuelve la\npropiedad `shadowRoot` del anfitrión. Un elemento `slot` del árbol de sombra marca dónde\naparecen los hijos del anfitrión. Muestra los nodos que se le asignan o su propio\ncontenido si no hay ninguno. Un slot con nombre recibe los hijos cuyo atributo `slot`\nlleva ese nombre. El elemento `template` contiene un fragmento HTML que no se representa\ny que un script puede clonar. Con un atributo `shadowrootmode`, un `template` representa\nuna raíz de sombra declarativa, de modo que también puede escribirse un árbol de\nsombra directamente en el marcado.\n\n## Por qué importa\n\nAntes, una etiqueta inventada servía de poco: HTML Standard recuerda aquellos elementos\ncomo inválidos y de escasa utilidad práctica. Un elemento personalizado es un miembro\npleno del documento. El analizador lo construye, los métodos del DOM lo crean y su\nclase decide qué ocurre cuando cambian sus atributos o entra o sale de una página.\n\nLa definición no tiene que llegar primero. Un elemento ya creado por el analizador\nse convierte en personalizado cuando se registra una definición para su nombre;\nHTML Standard lo llama actualización, o upgrading. Hasta entonces se trata como un\nelemento no definido, parecido a un `span`, y se muestran tal cual el texto y los\nenlaces que contiene. El estándar señala expresamente que estas actualizaciones\npermiten mejorar de forma progresiva el contenido de un elemento personalizado.\n\nUn elemento personalizado también puede participar en formularios y en el árbol de\naccesibilidad. Una clase que establece `static formAssociated = true` y llama a\n`attachInternals()` obtiene un objeto `ElementInternals`. En él, `setFormValue()` asigna\nal elemento un valor que su formulario envía como el de cualquier otro control.\nEl mismo objeto establece un rol ARIA y estados ARIA predeterminados, aplicados salvo\nque el autor de la página los sustituya mediante `role` o los atributos `aria-*`\ncorrespondientes. También puede contener estados personalizados que las hojas de\nestilos seleccionan con la pseudoclase `:state()`.\n\nPara un equipo, el árbol de sombra permite que el componente se baste a sí mismo:\nlos selectores ordinarios de la página no cruzan a su árbol de sombra interno, y el\ncomponente decide qué partes expone al estilo exterior. Los valores heredados y las\npropiedades personalizadas sí pueden entrar, y el contenido del árbol ligero colocado\nen slots sigue sujeto a los selectores de la página. Cuando varias bibliotecas\ncomparten una página, HTML Standard ofrece registros acotados, creados con\n`new CustomElementRegistry()`, para que sus elementos coexistan sin que las bibliotecas\ntengan que coordinar sus nombres.\n\n## Cómo se aplica en la práctica\n\nUna tarjeta de producto muestra cómo trabajan juntas las piezas. La página conserva\nel contenido como marcado ordinario, con un atributo `slot` en el elemento destinado\na un slot con nombre:\n\n```html\n\u003cproduct-card\u003e\n  \u003cspan slot=\"name\"\u003eOak stool\u003c/span\u003e\n  \u003ca href=\"/shop/oak-stool/\"\u003eSee the details\u003c/a\u003e\n\u003c/product-card\u003e\n\u003cscript type=\"module\" src=\"product-card.mjs\"\u003e\u003c/script\u003e\n```\n\nEl módulo define el elemento. La plantilla se construye una vez y cada tarjeta recibe\nsu propia copia en una raíz de sombra abierta:\n\n```js\nconst template = document.createElement(\"template\");\ntemplate.innerHTML = `\n  \u003ch2 part=\"title\"\u003e\u003cslot name=\"name\"\u003eUnnamed product\u003c/slot\u003e\u003c/h2\u003e\n  \u003cslot\u003e\u003c/slot\u003e\n`;\n\nclass ProductCard extends HTMLElement {\n  constructor() {\n    super();\n    const root = this.attachShadow({ mode: \"open\" });\n    root.append(template.content.cloneNode(true));\n  }\n}\n\nif (!customElements.get(\"product-card\")) {\n  customElements.define(\"product-card\", ProductCard);\n}\n```\n\nLa página aplica estilo al título mediante la única parte que expone el componente:\n\n```css\nproduct-card::part(title) {\n  font-size: 1.25rem;\n}\n```\n\nAntes de ejecutarse `product-card.mjs`, la tarjeta es un elemento no definido y el\nlector ve el nombre del producto y el enlace como contenido en línea normal. Cuando\nse ejecuta el módulo, `define()` registra la clase y se actualiza la tarjeta que ya\nestaba en la página. Su constructor añade una raíz de sombra y la llena con un clon\ndel contenido de la plantilla. El `span` se asigna al slot llamado `name` y aparece\ndentro del encabezado. El enlace no tiene atributo `slot`, por lo que ocupa el slot\npredeterminado sin nombre. Una tarjeta sin nombre muestra en su lugar el contenido\ndel propio slot, «Unnamed product» («producto sin nombre»). La comprobación `customElements.get()` evita que\nuna segunda copia del módulo, llegada en otro paquete, haga fallar `define()`.\n\nLos componentes compartidos solo ayudan si se usan, y el portafolio del sitio recoge\nun caso al respecto.\n[El sistema de diseño «Liquid Glass» de iOS 26](/es/portfolio/designed-an-ios-26-liquid-glass-design-system/)\nparte de una interfaz en la que cada pantalla nueva reinventa botones, insignias y\ntarjetas, con pequeñas diferencias, hasta que cada cambio exige retocar cinco versiones\nhechas a medida. La respuesta descrita es un conjunto canónico de componentes a partir del que\nse construyen todas las pantallas. Entre esos componentes están Card, Label, Button,\nGlassIconButton y DirectoryGrid, con reglas de análisis que rechazan una insignia o un chip hechos a mano\ny remiten al componente canónico. La página no dice si son elementos personalizados,\npero la disciplina se aplica igual: una definición por componente, impuesta mediante\nherramientas y no por la memoria del revisor. El registro de elementos personalizados\nimpone la primera mitad al rechazar una segunda definición para un mismo nombre.\n\n## Dónde surgen los problemas\n\n**Un nombre con guion hace las veces de rol.** «Un elemento personalizado autónomo no\ntiene ningún significado especial: representa a sus hijos», dice HTML Standard.\nSu ejemplo `taco-button` muestra el coste: para actuar como botón necesita `tabindex`,\nel rol ARIA `button`, un nombre accesible, `aria-disabled`, manejadores de teclas que\nconviertan Intro y Espacio en clics y estilos para el estado desactivado. Aun así, un\nelemento personalizado no puede declarar el comportamiento de foco predeterminado,\npor lo que `tabindex=\"0\"` puede no coincidir con los botones de la plataforma. Cuando\nel elemento parte de uno existente, el estándar indica que extender uno integrado\nreduce el trabajo de su autor y de sus usuarios. Para uno autónomo, establezca el rol\ny los estados predeterminados mediante `ElementInternals`, en lugar de dejarlos a\ncada página que lo use.\n\n**El constructor hace todo el trabajo.** HTML Standard impone reglas a los constructores\nde elementos personalizados: primero va `super()` sin argumentos; el constructor no\ndebe consultar los atributos ni los hijos del elemento, porque uno creado en vez de\nactualizado no tiene ninguno; y el elemento no debe adquirir atributos ni hijos propios.\nIncumplir esas reglas puede producir un elemento que el analizador o los métodos DOM\nno logren crear. Reserve el constructor para el estado inicial, los valores\npredeterminados, los receptores de eventos y la raíz de sombra, y traslade la obtención\nde datos y la representación a `connectedCallback`.\n\n**Se espera que `connectedCallback` se ejecute una sola vez.** Puede ejecutarse varias.\nDe forma predeterminada, mover un elemento ejecuta `disconnectedCallback` y después\n`connectedCallback`, de modo que el elemento reinicia su estado como si se hubiera\nretirado e insertado de nuevo. Proteja con un indicador la preparación que solo debe\nocurrir una vez y deshaga en `disconnectedCallback` lo iniciado por `connectedCallback`.\nSi debe conservar su estado al moverse con `moveBefore()`, defina `connectedMoveCallback`:\nsu mera presencia sustituye a la pareja predeterminada, incluso con el cuerpo vacío.\n\n**Un nombre se define dos veces.** `customElements.define()` lanza `NotSupportedError`\nsi ya están registrados el nombre o la clase, y `SyntaxError` si el nombre no es válido,\npor ejemplo porque no tiene guion o contiene una mayúscula. Compruebe antes con\n`customElements.get()` y dé un registro acotado propio a una biblioteca que deba\ncoexistir con otras.\n\n**El modo cerrado se trata como protección.** El modo cerrado oculta la raíz a la\npropiedad `shadowRoot` del anfitrión y oculta los nodos internos de la ruta compuesta\nde un evento tal como la ven los receptores externos a ese árbol de sombra cerrado.\nCSS Shadow Parts afirma claramente que los árboles de sombra no se concibieron como\nuna barrera de seguridad, sino como una comodidad para los autores de páginas. Mantenga\nlos secretos fuera de los componentes y elija el modo cerrado por su efecto sobre\nel código exterior, no como cerradura.\n\n**Se llama a `attachShadow()` donde no puede funcionar.** DOM Standard solo permite una\nraíz de sombra en elementos con un nombre válido de elemento personalizado y en una\nlista breve de elementos integrados: entre ellos `div`, `section`, `p` y `span`, pero\nno `button`. En un botón integrado personalizado, la llamada lanza `NotSupportedError`.\nTambién cambia su comportamiento si el elemento ya tiene una raíz: si es declarativa\ny del mismo modo, la llamada elimina todo su contenido y la devuelve vacía; en los\ndemás casos lanza una excepción. Compruebe primero si existe una raíz de sombra para\nconservar, en vez de borrar, el marcado que el servidor envió en una raíz declarativa.\n\n**Se espera que los estilos de la página lleguen al interior.** CSS Shadow Parts llama\nal límite barrera de estilo y señala que también dificulta personalizar el componente\ncuando la página lo necesita. Exponga con `part` los elementos a los que la página\npueda dar estilo y selecciónelos desde fuera con `::part()`. Un componente anidado en\notro necesita `exportparts` en su anfitrión interior para transmitir sus partes a la\npágina. Para colores y espaciados que deban seguirla, lea las propiedades personalizadas\ndefinidas en el anfitrión, que alcanzan el árbol de sombra por herencia.\n\n**El contenido solo existe después del script.** Un componente que escribe todo su texto\ncon JavaScript no muestra nada a los lectores hasta cargar la definición, y nada en\nabsoluto si el script falla. Conserve el contenido en el árbol ligero y asígnelo a\nslots, como hace la tarjeta de producto, para que la actualización mejore lo que ya\nexiste. Si el contenido debe esperar, el ejemplo del propio HTML Standard lo oculta\nhasta que `customElements.whenDefined()` se resuelve para cada elemento que coincide\ncon `:not(:defined)`.\n\n## Lecturas adicionales\n\n- [HTML Standard: Custom elements](https://html.spec.whatwg.org/multipage/custom-elements.html)\n  — reglas de nombres, requisitos de constructores, actualizaciones, elementos asociados\n  a formularios y `ElementInternals`, con ejemplos completos.\n- [DOM Standard: Shadow tree](https://dom.spec.whatwg.org/#shadow-trees) — raíces de sombra\n  y sus anfitriones, slots y nodos asignados, y los pasos de `attachShadow()`.\n- [HTML Standard: Scripting](https://html.spec.whatwg.org/multipage/scripting.html) — el\n  elemento `template` con su atributo `shadowrootmode` y el elemento `slot`.\n- [CSS Shadow Parts](https://www.w3.org/TR/css-shadow-parts-1/) — el borrador de trabajo\n  del W3C de 16 de diciembre de 2025 que define `part`, `exportparts` y el pseudoelemento\n  `::part()`.\n\n\u003chttps://engineer.company/es/glossary/web-components/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Cómo los elementos personalizados, árboles de sombra, template y slot permiten crear etiquetas HTML propias, con un ejemplo completo y sus riesgos.","formats":{"gemtext":"https://engineer.company/es/glossary/web-components/index.gmi","gopher":"https://engineer.company/es/glossary/web-components/gophermap","html":"https://engineer.company/es/glossary/web-components/","json":"https://engineer.company/es/glossary/web-components/index.json","markdown":"https://engineer.company/es/glossary/web-components/index.md","pdf":"https://engineer.company/es/glossary/web-components/index.pdf"},"kind":"page","language":"es","title":"¿Qué son los componentes web?","url":"https://engineer.company/es/glossary/web-components/","version":1}