Tutorial de Web Components
Elementos personalizados nativos, sin entorno de ejecución de framework. Cada uno genera un
<button> o un <input> real en el DOM ligero, así que los formularios, el CSS y querySelector funcionan como en HTML escrito a mano.
Lo que vas a construir
Un pequeño formulario de contacto con campos etiquetados y un botón de envío, conectado con unas pocas líneas de script, primero sin estilo y luego con estilo, en unos 10 minutos.
Antes de empezar
Necesitas Node.js y un empaquetador o cualquier configuración que resuelva importaciones de módulos sin ruta. El catálogo cubre 626 de los 661 componentes; los subelementos de tabla y algunas familias de elementos de lista quedan fuera, porque un elemento personalizado autónomo no puede sustituir a un <tr>
ni a un <li>.
Paso 1 — Instalar y registrar
npm install @lilydesignsystem/web-components-headless
<script type="module">
import "@lilydesignsystem/web-components-headless";
</script>
Al importar el paquete se define cada elemento, con el nombre
lily- más el identificador del componente:
<lily-button>, <lily-text-input>,
<lily-range-fieldset>.
Paso 2 — Tu primer componente
<lily-button type="submit">Send</lily-button>
El elemento genera un <button class="button">
real dentro de sí mismo, así que Intro, Espacio y el rol de botón son nativos. Los atributos que añadas pasan a ese elemento interno.
Paso 3 — Componer un formulario pequeño
<lily-form label="Contact us">
<lily-field label="Full name" required>
<lily-text-input label="Full name" name="name" autocomplete="name" required></lily-text-input>
</lily-field>
<lily-field label="Email" required>
<lily-email-input label="Email" name="email" required></lily-email-input>
</lily-field>
<lily-button type="submit">Send</lily-button>
</lily-form>
<script type="module">
const form = document.querySelector("lily-form form");
form.addEventListener("submit", () => {
const data = new FormData(form);
console.log(Object.fromEntries(data));
});
</script>
<lily-form> impide la navegación de la página y deja que el evento
submit se propague, así que tu script decide qué ocurre. Los campos son controles de formulario auténticos, así que FormData los lee.
Comprueba tu trabajo: pulsa Tab para recorrer el formulario y envíalo: la consola muestra name y
email. Deja un campo vacío y la comprobación
required del propio navegador detiene el envío.
Paso 4 — Darle estilo
Las clases están en los elementos internos, así que los 63 temas y tu propio CSS los alcanzan como en HTML sencillo:
<link rel="stylesheet" href="/themes/light.css" />
<style>
.button { padding: 0.75rem 1.5rem; }
lily-field { display: block; margin-block-end: 1rem; }
</style>
No hay shadow DOM que atravesar: nada queda oculto a tu hoja de estilos ni a las tecnologías de apoyo.
Paso 5 — Verlo todo funcionando
- Cada elemento tiene una story:
pnpm run storybookenlily-design-system-web-components-headless. -
Los ayudantes también se publican como elementos personalizados:
<lily-theme-picker>, la cuadrícula de datos, el calendario y los demás (@lilydesignsystem/web-components-*).
Próximos pasos
- Formación — ocho módulos, cada uno con un ejercicio y una autoevaluación.
- Formularios accesibles — errores, un resumen de errores y el foco.
- Temas — cambiar de tema en tiempo de ejecución.
- Catálogo de componentes — la referencia completa.