Tutoriel Web Components

Des éléments personnalisés natifs, sans environnement d'exécution de framework. Chacun produit un vrai <button> ou <input> dans le DOM léger, si bien que les formulaires, le CSS et querySelector fonctionnent comme sur du HTML écrit à la main.

Ce que vous allez construire

Un petit formulaire de contact avec des champs étiquetés et un bouton d'envoi, relié par quelques lignes de script, d'abord nu, puis stylé, en 10 minutes environ.

Avant de commencer

Il vous faut Node.js et un bundler ou toute configuration qui résout les imports de modules nus. Le catalogue couvre 626 des 661 composants ; les sous-éléments de tableau et quelques familles d'éléments de liste sont laissés de côté, car un élément personnalisé autonome ne peut pas remplacer un <tr> ou un <li>.

Étape 1 — Installer et enregistrer

npm install @lilydesignsystem/web-components-headless
<script type="module">
  import "@lilydesignsystem/web-components-headless";
</script>

Importer le paquet définit chaque élément, chacun nommé lily- suivi de l'identifiant du composant : <lily-button>, <lily-text-input>, <lily-range-fieldset>.

Étape 2 — Votre premier composant

<lily-button type="submit">Send</lily-button>

L'élément produit un vrai <button class="button"> à l'intérieur de lui-même : Entrée, Espace et le rôle de bouton sont donc natifs. Les attributs que vous ajoutez sont transmis à cet élément interne.

Étape 3 — Composer un petit formulaire

<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> empêche la navigation de la page et laisse l'événement submit remonter : votre script décide de la suite. Les champs sont de vrais contrôles de formulaire, donc FormData les lit.

Vérifiez votre travail : appuyez sur Tab pour parcourir le formulaire, puis envoyez-le : la console affiche name et email. Laissez un champ vide et la vérification required propre au navigateur bloque l'envoi.

Étape 4 — Le styliser

Les classes se trouvent sur les éléments internes : les 63 thèmes et votre propre CSS les ciblent comme sur du HTML simple :

<link rel="stylesheet" href="/themes/light.css" />

<style>
  .button { padding: 0.75rem 1.5rem; }
  lily-field { display: block; margin-block-end: 1rem; }
</style>

Il n'y a pas de shadow DOM à traverser : rien n'est caché à votre feuille de style ni aux technologies d'assistance.

Étape 5 — Tout voir fonctionner

  • Chaque élément a une story : pnpm run storybook dans lily-design-system-web-components-headless.
  • Les assistants existent aussi sous forme d'éléments personnalisés : <lily-theme-picker>, la grille de données, le calendrier et les autres (@lilydesignsystem/web-components-*).

Étapes suivantes