Tutoriel Alpine.js

Lily pour Alpine, ce sont des fragments HTML que vous collez dans votre page, plus un plugin qui donne aux composants interactifs leur clavier et leur état.

Ce que vous allez construire

Un petit formulaire de réglages : deux champs étiquetés, un interrupteur et un bouton d'enregistrement, avec un vrai comportement au clavier et au lecteur d'écran, d'abord nu, puis stylé, en 10 minutes environ.

Avant de commencer

Il vous faut Node.js et une page qui charge déjà Alpine.js 3. Alpine n'a pas de modèle de composants : un composant Lily est ici du balisage que l'on copie, pas un import.

Étape 1 — Installer et enregistrer le plugin

npm install alpinejs @lilydesignsystem/alpine-headless
<script type="module">
  import Alpine from "alpinejs";
  import lily from "@lilydesignsystem/alpine-headless/plugin";
  Alpine.plugin(lily);
  Alpine.start();
</script>

Le plugin enregistre un comportement Alpine.data() par composant interactif, nommé lily suivi du nom du composant : lilySwitchButton, lilyTabs, lilyCombobox. Les fragments de chaque composant se trouvent dans le dossier components/ du paquet, chacun avec un commentaire d'en-tête qui indique son élément, sa classe, ses touches et son ARIA.

Étape 2 — Votre premier composant

La plupart des composants sont du simple balisage et n'ont besoin de rien du plugin :

<button class="button" type="submit">Save</button>

Un composant interactif ajoute son comportement avec x-data et le lie avec x-bind:

<button
  class="switch-button"
  x-data="lilySwitchButton(false)"
  x-bind="button"
  aria-label="Email me about appointments"
>
  Email me about appointments
</button>

Le comportement lui donne role="switch" et maintient aria-checked à jour quand Entrée, Espace ou un clic le bascule. Les mots sont les vôtres : Lily ne fournit jamais d'étiquette.

Étape 3 — Composer un petit formulaire

<form class="form" aria-label="Settings">
  <div class="field">
    <label class="label" for="name">Full name</label>
    <input class="text-input" type="text" id="name" name="name" autocomplete="name" required />
  </div>
  <div class="field">
    <label class="label" for="email">Email</label>
    <input class="email-input" type="email" id="email" name="email" autocomplete="email" required />
  </div>
  <button
    class="switch-button"
    type="button"
    x-data="lilySwitchButton(true)"
    x-bind="button"
    aria-label="Email me about appointments"
  >
    Email me about appointments
  </button>
  <button class="button" type="submit">Save</button>
</form>

Vérifiez votre travail : ouvrez la page et appuyez sur Tab. Le focus parcourt les deux champs, l'interrupteur et le bouton. Sur l'interrupteur, Space le bascule, et un lecteur d'écran annonce « interrupteur, activé » ou « désactivé ». L'aspect est sobre, et c'est normal : le style vient ensuite.

Étape 4 — Le styliser

Liez l'un des 63 thèmes prêts à l'emploi, qui ciblent les mêmes classes :

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

Ou écrivez votre propre CSS sur les classes et l'état que fixe le comportement :

.switch-button[aria-checked="true"] { background: var(--color-primary); }
.switch-button:focus-visible { outline: 2px solid var(--lily-focus-ring); outline-offset: 2px; }

Stylez l'état ARIA, pas une classe à vous : ainsi l'apparence ne peut jamais contredire ce qu'entend un lecteur d'écran.

Étape 5 — Tout voir fonctionner

  • L'application d'exemple Alpine.js, lily-design-system-alpine-examples, montre chaque composant stylé : pnpm install && pnpm run build.
  • Six assistants existent pour Alpine : la grille de données, le tableau kanban, le calendrier, le diagramme de Gantt et les éditeurs Markdown et Org (@lilydesignsystem/alpine-*).

Étapes suivantes