# Alpinejs
> This skill should be used when the user asks to "add Alpine.js", "create Alpine component", "use Alpine directives", "build interactive UI with Alpine", or needs guidance on Alpine.js development patterns and best practices.
- Skill: `the-perfect-developer/alpinejs` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add the-perfect-developer/alpinejs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/the-perfect-developer/alpinejs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: the-perfect-developer (https://skillmd.com/u/the-perfect-developer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/the-perfect-developer/alpinejs
---
# Alpine.js Development
Build reactive, declarative interfaces by adding Alpine.js directives directly to HTML markup.
## What is Alpine.js
Alpine.js is a lightweight JavaScript framework that provides reactive and declarative behavior directly in HTML markup. It offers Vue-like syntax and reactivity without the build step, making it perfect for enhancing static sites or adding interactivity to server-rendered pages.
**Key characteristics**:
- No build step required - include via CDN or npm
- Declarative syntax using HTML attributes (directives)
- Reactive data binding and state management
- Small footprint (~15kb gzipped)
- Works seamlessly with server-rendered HTML
## Installation
### Via CDN (Quick Start)
Add the script tag to your HTML ``:
```html
```
The `defer` attribute ensures Alpine loads after the HTML is parsed.
### Via npm
```bash
npm install alpinejs
```
Then import and initialize:
```javascript
import Alpine from 'alpinejs'
window.Alpine = Alpine
Alpine.start()
```
## Core Concepts
### State with x-data
Declare reactive state using the `x-data` directive. All Alpine components start with `x-data`:
```html
```
**Key points**:
- Define data as a JavaScript object
- Properties are reactive - changes trigger UI updates
- Data is scoped to the element and its children
- Child elements can override parent data properties
### Event Handling with x-on
Listen to browser events using `x-on:` or the `@` shorthand:
```html
```
**Common event modifiers**:
- `.prevent` - Prevent default behavior
- `.stop` - Stop event propagation
- `.outside` - Trigger when clicking outside element
- `.window` - Listen on window object
- `.debounce` - Debounce the handler
**Key-specific listeners**:
```html
```
### Templating and Display
**x-text** - Set element text content:
```html
```
**x-html** - Set element HTML (use only with trusted content):
```html
```
**x-show** - Toggle visibility with CSS display property:
```html
Content
```
**x-if** - Conditionally add/remove element from DOM:
```html
Content
```
**When to use x-show vs x-if**:
- Use `x-show` when toggling frequently (keeps element in DOM)
- Use `x-if` when conditionally rendering expensive content
### Looping with x-for
Iterate over arrays to render lists:
```html
```
**Requirements**:
- Must be on a `` element
- Should include `:key` for proper tracking
### Binding Attributes with x-bind
Dynamically bind HTML attributes using `x-bind:` or `:` shorthand:
```html
```
**Class binding** (special object syntax):
```html
```
**Style binding**:
```html
```
### Two-Way Binding with x-model
Bind input values to data properties:
```html
```
**Modifiers**:
- `.number` - Convert to number
- `.debounce` - Debounce input
- `.throttle` - Throttle input
## Common Patterns
### Toggle Component
```html
```
## Global State
Share state across components using `Alpine.store()`:
```javascript
Alpine.store('auth', {
user: null,
loggedIn: false,
login(user) {
this.user = user
this.loggedIn = true
}
})
```
Access in templates:
```html
```
## Magic Properties
Alpine provides magic properties accessible anywhere:
- `$el` - Reference to current DOM element
- `$refs` - Access elements marked with `x-ref`
- `$store` - Access global stores
- `$watch` - Watch for data changes
- `$dispatch` - Dispatch custom events
- `$nextTick` - Execute after next DOM update
- `$root` - Access root element of component
- `$data` - Access entire data object
- `$id` - Generate unique IDs
**Example using $refs**:
```html
```
## Best Practices
**Keep data objects simple** - Start with minimal state and add as needed:
```html
```
**Use getters for computed values**:
```javascript
{
items: [1, 2, 3],
get total() {
return this.items.reduce((sum, i) => sum + i, 0)
}
}
```
**Prevent FOUC (Flash of Unstyled Content)** with `x-cloak`:
```html
```
**Extract complex logic to Alpine.data()**:
```javascript
// Instead of inline in HTML
Alpine.data('complexForm', () => ({
// Complex initialization and methods
}))
```
**Use event modifiers appropriately**:
```html