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 storybook en lily-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