Alpine.js tutorial
Lily for Alpine is HTML snippets you paste into your page, plus one plugin that gives the interactive ones their keyboard and state.
What you'll build
A small settings form: two labelled fields, a switch, and a save button, with real keyboard and screen-reader behaviour, first bare, then styled, in about 10 minutes.
Before you start
You need Node.js and a page that already loads Alpine.js 3. Alpine has no component model, so a Lily component here is markup you copy, not an import.
Step 1 — Install and register the 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> The plugin registers one Alpine.data() behaviour per
interactive component, named lily plus the component's name: lilySwitchButton, lilyTabs, lilyCombobox. The snippets for every component are in the
package's components/ folder, each with a header comment
giving its element, class hook, keys and ARIA.
Step 2 — Your first component
Most components are plain markup and need nothing from the plugin:
<button class="button" type="submit">Save</button> An interactive one adds its behaviour with x-data and binds it with x-bind:
<button
class="switch-button"
x-data="lilySwitchButton(false)"
x-bind="button"
aria-label="Email me about appointments"
>
Email me about appointments
</button> The behaviour gives it role="switch" and keeps aria-checked in step as Enter, Space or a click toggles it.
The words are yours: Lily never supplies a label.
Step 3 — Compose a small form
<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> Check your work: open the page and press Tab. Focus moves through both fields, the switch and the button. On the switch, Space toggles it, and a screen reader says "switch, on" or "off". It looks plain, which is right: the look is next.
Step 4 — Style it
Link one of the 63 ready-made themes, which target the same class hooks:
<link rel="stylesheet" href="/themes/light.css" /> Or write your own CSS against the hooks and the state the behaviour sets:
.switch-button[aria-checked="true"] { background: var(--color-primary); }
.switch-button:focus-visible { outline: 2px solid var(--lily-focus-ring); outline-offset: 2px; } Style the ARIA state, not a class of your own: then the look can never disagree with what a screen reader hears.
Step 5 — See it all working
- The Alpine.js example app,
lily-design-system-alpine-examples, shows every component styled:pnpm install && pnpm run build. - Six helpers ship for Alpine: the data grid, kanban board, calendar,
Gantt chart and the Markdown and Org editors
(
@lilydesignsystem/alpine-*).
Next steps
- Training — eight modules, each with an exercise and a self-check.
- Accessible forms — errors, an error summary and focus.
- Theming — runtime theme switching.
- Component catalog — the full reference.