Tutorial de Alpine.js
Lily para Alpine son fragmentos HTML que pegas en tu página, más un plugin que da a los interactivos su teclado y su estado.
Lo que vas a construir
Un pequeño formulario de ajustes: dos campos etiquetados, un interruptor y un botón de guardar, con comportamiento real de teclado y lector de pantalla, primero sin estilo y luego con estilo, en unos 10 minutos.
Antes de empezar
Necesitas Node.js y una página que ya cargue Alpine.js 3. Alpine no tiene modelo de componentes, así que aquí un componente de Lily es marcado que copias, no un import.
Paso 1 — Instalar y registrar el 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>
El plugin registra un comportamiento Alpine.data() por cada componente interactivo, con el nombre lily más el nombre del componente:
lilySwitchButton, lilyTabs,
lilyCombobox. Los fragmentos de todos los componentes están en la carpeta components/ del paquete, cada uno con un comentario inicial que indica su elemento, su clase, sus teclas y su ARIA.
Paso 2 — Tu primer componente
La mayoría de los componentes son marcado sencillo y no necesitan nada del plugin:
<button class="button" type="submit">Save</button>
Uno interactivo añade su comportamiento con x-data y lo enlaza con x-bind:
<button
class="switch-button"
x-data="lilySwitchButton(false)"
x-bind="button"
aria-label="Email me about appointments"
>
Email me about appointments
</button>
El comportamiento le da role="switch" y mantiene
aria-checked al día cuando Intro, Espacio o un clic lo alternan. Las palabras son tuyas: Lily nunca proporciona una etiqueta.
Paso 3 — Componer un formulario pequeño
<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>
Comprueba tu trabajo: abre la página y pulsa Tab. El foco recorre ambos campos, el interruptor y el botón. En el interruptor, Space lo alterna y un lector de pantalla dice «interruptor, activado» o «desactivado». Se ve sencillo, y es lo correcto: el aspecto viene después.
Paso 4 — Darle estilo
Enlaza uno de los 63 temas listos para usar, que apuntan a las mismas clases:
<link rel="stylesheet" href="/themes/light.css" />
O escribe tu propio CSS sobre las clases y el estado que fija el comportamiento:
.switch-button[aria-checked="true"] { background: var(--color-primary); }
.switch-button:focus-visible { outline: 2px solid var(--lily-focus-ring); outline-offset: 2px; }
Da estilo al estado ARIA, no a una clase propia: así el aspecto nunca puede contradecir lo que oye un lector de pantalla.
Paso 5 — Verlo todo funcionando
-
La aplicación de ejemplo de Alpine.js,
lily-design-system-alpine-examples, muestra todos los componentes con estilo:pnpm install && pnpm run build. -
Hay seis ayudantes para Alpine: la cuadrícula de datos, el tablero kanban, el calendario, el diagrama de Gantt y los editores de Markdown y Org (
@lilydesignsystem/alpine-*).
Próximos pasos
- Formación — ocho módulos, cada uno con un ejercicio y una autoevaluación.
- Formularios accesibles — errores, un resumen de errores y el foco.
- Temas — cambiar de tema en tiempo de ejecución.
- Catálogo de componentes — la referencia completa.