Tutorial Alpine.js

Lily untuk Alpine adalah cuplikan HTML yang Anda tempel ke halaman, ditambah satu plugin yang memberi komponen interaktif papan ketik dan keadaannya.

Yang akan Anda buat

Formulir pengaturan kecil: dua isian berlabel, sakelar, dan tombol simpan, dengan perilaku papan ketik dan pembaca layar yang sungguhan, polos dulu lalu bergaya, dalam sekitar 10 menit.

Sebelum memulai

Anda memerlukan Node.js dan halaman yang sudah memuat Alpine.js 3. Alpine tidak punya model komponen, jadi di sini komponen Lily adalah markah yang Anda salin, bukan impor.

Langkah 1 — Pasang dan daftarkan 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>

Plugin mendaftarkan satu perilaku Alpine.data() untuk setiap komponen interaktif, bernama lily ditambah nama komponennya: lilySwitchButton, lilyTabs, lilyCombobox. Cuplikan setiap komponen ada di folder components/ paket, masing-masing dengan komentar kepala yang menyebut elemen, kelas, tombol, dan ARIA-nya.

Langkah 2 — Komponen pertama Anda

Sebagian besar komponen adalah markah biasa dan tidak memerlukan apa pun dari plugin:

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

Komponen interaktif menambahkan perilakunya dengan x-data dan mengikatnya dengan x-bind:

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

Perilaku itu memberinya role="switch" dan menjaga aria-checked tetap sesuai saat Enter, Spasi, atau klik mengubahnya. Kata-katanya milik Anda: Lily tidak pernah memberikan label.

Langkah 3 — Susun formulir kecil

<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>

Periksa hasil kerja Anda: buka halaman dan tekan Tab. Fokus berpindah melalui kedua isian, sakelar, dan tombol. Pada sakelar, Space mengubahnya, dan pembaca layar mengucapkan "sakelar, aktif" atau "nonaktif". Tampilannya polos, dan memang begitu: gayanya berikutnya.

Langkah 4 — Beri gaya

Tautkan salah satu dari 63 tema siap pakai, yang menyasar kelas yang sama:

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

Atau tulis CSS sendiri pada kelas dan keadaan yang ditetapkan perilaku:

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

Beri gaya pada keadaan ARIA, bukan kelas buatan sendiri: dengan begitu tampilan tidak akan pernah berbeda dengan yang didengar pembaca layar.

Langkah 5 — Lihat semuanya bekerja

  • Aplikasi contoh Alpine.js, lily-design-system-alpine-examples, menampilkan setiap komponen bergaya: pnpm install && pnpm run build.
  • Ada enam pembantu untuk Alpine: kisi data, papan kanban, kalender, bagan Gantt, serta penyunting Markdown dan Org (@lilydesignsystem/alpine-*).

Langkah berikutnya