Below is a comprehensive reference guide for Alpine.js—a lightweight, declarative JavaScript framework that brings reactivity right into your HTML. This tutorial explains its primary directives (or “attributes”), properties, and methods in clear language with concrete examples. Whether you’re adding a touch of interactivity or building a fully dynamic component, this guide will help you determine when to use each tool and what they’re best for.
1. Introduction#
Alpine.js is designed to be a minimal, yet powerful tool that lets you add JavaScript behavior to your markup without a heavy framework. It uses custom HTML attributes to bind data, handle events, apply conditionals, iterate over lists, and much more. Think of it as a sprinkle of Vue-like reactivity on top of your HTML—perfect for small projects, adding interactivity, or progressive enhancement.
2. Getting Started#
To start using Alpine.js, simply include the CDN in your HTML header:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Alpine.js Example</title>
<!-- Include Alpine.js from CDN -->
<script src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js" defer></script>
</head>
<body>
<!-- Your Alpine-enabled markup goes here -->
</body>
</html>
Syntax Breakdown:
SCRIPT element:
src attribute: Load external script from "https://..."
defer attribute: Execute script after HTML parsing is complete.
Be sure to include the script with the defer attribute so that Alpine initializes after the DOM has loaded.
3. Core Directives#
Alpine works by binding state and behavior through special HTML attributes. Here are the foundational directives:
3.1 x-data#
What it does:
Initializes a component’s state. Declare an object containing your application data.
When to use it:
Use x-data on any element that acts as a container for your reactive data. This is analogous to Vue’s data function.
Example:
<div x-data="{ count: 0, message: 'Hello, Alpine!' }">
<p x-text="message"></p>
<button @click="count++">Count: <span x-text="count"></span></button>
</div>
Syntax Breakdown:
DIV element:
x-data directive: Initialize Alpine component state.
Value: JavaScript object { count: 0, message: 'Hello, Alpine!' }
- count: state property, initial value 0
- message: state property, initial value 'Hello, Alpine!'
P element:
x-text directive: Set element's text content.
Value: Evaluate state property 'message'.
BUTTON element:
@click directive (shorthand for x-on:click): Add click event listener.
Value: Execute JavaScript 'count++' (increment state property 'count').
SPAN element:
x-text directive: Set element's text content.
Value: Evaluate state property 'count'.
In this example, the <div> becomes reactive, holding a data object with count and message.
3.2 x-init#
What it does:
Executes JavaScript code as soon as the component initializes. Great for setting initial conditions or fetching data.
When to use it:
Use x-init to run code once your component loads, such as initializing variables or running animations.
Example:
<div x-data="{ message: '' }" x-init="message = 'Component Initialized!'">
<p x-text="message"></p>
</div>
Syntax Breakdown:
DIV element:
x-data directive: Initialize Alpine component state.
Value: JavaScript object { message: '' }
- message: state property, initial value ''
x-init directive: Execute JavaScript upon component initialization.
Value: Execute JavaScript 'message = "Component Initialized!"' (assign value to state property 'message').
P element:
x-text directive: Set element's text content.
Value: Evaluate state property 'message'.
Here, when the component initializes, x-init sets the message variable.
3.3 x-bind#
What it does:
Dynamically binds an HTML attribute to an expression. It’s used to update element attributes on the fly.
When to use it:
Use x-bind when you need to set attributes like class, src, href, etc., based on your component’s state.
Example:
<div x-data="{ isActive: true }">
<!-- Long form: -->
<button x-bind:class="{ 'bg-blue-500': isActive, 'bg-gray-500': !isActive }">
Toggle Class
</button>
<!-- Shorthand: -->
<button :class="{ 'bg-blue-500': isActive, 'bg-gray-500': !isActive }">
Toggle Class
</button>
</div>
Syntax Breakdown:
DIV element:
x-data directive: Initialize Alpine component state.
Value: JavaScript object { isActive: true }
- isActive: state property, initial value true
BUTTON element (long form):
x-bind:class directive: Dynamically bind the 'class' attribute.
Value: JavaScript object { 'bg-blue-500': isActive, 'bg-gray-500': !isActive }
- If 'isActive' evaluates to true, add class 'bg-blue-500'.
- If '!isActive' evaluates to true, add class 'bg-gray-500'.
BUTTON element (shorthand):
:class directive (shorthand for x-bind:class): Dynamically bind the 'class' attribute.
Value: JavaScript object { 'bg-blue-500': isActive, 'bg-gray-500': !isActive }
- (Same logic as above)
The button’s background color switches based on the value of isActive.
3.4 x-on (and its shorthand @)#
What it does:
Attaches event listeners to elements. It listens for DOM events and executes expressions in response.
When to use it:
Use x-on to handle clicks, mouse events, keyboard events, etc.
Example:
<div x-data="{ count: 0 }">
<button x-on:click="count++">Increment</button>
<p>Count is: <span x-text="count"></span></p>
<!-- Shorthand syntax: -->
<button @click="count--">Decrement</button>
</div>
Syntax Breakdown:
DIV element:
x-data directive: Initialize Alpine component state.
Value: JavaScript object { count: 0 }
- count: state property, initial value 0
BUTTON element (long form):
x-on:click directive: Add click event listener.
Value: Execute JavaScript 'count++' (increment state property 'count').
P element:
SPAN element:
x-text directive: Set element's text content.
Value: Evaluate state property 'count'.
BUTTON element (shorthand):
@click directive (shorthand for x-on:click): Add click event listener.
Value: Execute JavaScript 'count--' (decrement state property 'count').
Events (using the full syntax x-on:event or shorthand @event) allow you to easily react to user interactions.
3.5 x-model#
What it does:
Creates two-way data binding between form inputs and your application’s data.
When to use it:
Use x-model on form elements like <input>, <textarea>, or <select> to bind their values to your component’s state.
Example:
<div x-data="{ name: 'Alpine' }">
<input type="text" x-model="name" placeholder="Enter your name">
<p>Hello, <span x-text="name"></span>!</p>
</div>
Syntax Breakdown:
DIV element:
x-data directive: Initialize Alpine component state.
Value: JavaScript object { name: 'Alpine' }
- name: state property, initial value 'Alpine'
INPUT element (type="text"):
x-model directive: Create two-way binding between input value and state property.
Value: Bind to state property 'name'.
P element:
SPAN element:
x-text directive: Set element's text content.
Value: Evaluate state property 'name'.
As you type, the greet text updates in real time.
3.6 x-show#
What it does:
Conditionally shows or hides elements by toggling the element’s CSS (display: none).
When to use it:
Use x-show when you want to conditionally display content without completely removing it from the DOM (so that transitions or state remain intact).
Example:
<div x-data="{ open: false }">
<button @click="open = !open">Toggle Details</button>
<div x-show="open">
<p>Here are some details that can be toggled.</p>
</div>
</div>
Syntax Breakdown:
DIV element:
x-data directive: Initialize Alpine component state.
Value: JavaScript object { open: false }
- open: state property, initial value false
BUTTON element:
@click directive: Add click event listener.
Value: Execute JavaScript 'open = !open' (toggle boolean state property 'open').
DIV element:
x-show directive: Conditionally toggle element's visibility (CSS display).
Value: Evaluate boolean state property 'open'. Show if true, hide if false.
Toggle the open state to determine when the details are visible.
3.7 x-for#
What it does:
Loops over arrays or objects to render a list of elements.
When to use it:
Use x-for when you need to render multiple components from an array of data.
Example:
<div x-data="{ items: ['Apple', 'Banana', 'Cherry'] }">
<ul>
<template x-for="(item, index) in items" :key="index">
<li x-text="item"></li>
</template>
</ul>
</div>
Syntax Breakdown:
DIV element:
x-data directive: Initialize Alpine component state.
Value: JavaScript object { items: ['Apple', 'Banana', 'Cherry'] }
- items: state property, initial value Array['Apple', 'Banana', 'Cherry']
UL element:
TEMPLATE element: Define template for iteration.
x-for directive: Iterate over an array/object.
Value: "(item, index) in items"
- Iterate over state property 'items'.
- Assign current element to loop variable 'item'.
- Assign current index to loop variable 'index'.
:key directive (shorthand for x-bind:key): Bind the 'key' attribute for list rendering optimization.
Value: Evaluate loop variable 'index'.
LI element (inside template):
x-text directive: Set element's text content.
Value: Evaluate loop variable 'item'.
Notice the use of <template> as a container for the looped elements. Alpine will render a list item for every element in the items array.
3.8 x-ref#
What it does:
Registers a reference to an element, making it accessible in your component’s JavaScript context.
When to use it:
Use x-ref when you need to programmatically interact with a DOM element—for example, setting focus on an input or measuring element dimensions.
Example:
<div x-data="{ focusInput() { $refs.myInput.focus(); } }">
<input type="text" x-ref="myInput" placeholder="Focus me!">
<button @click="focusInput()">Focus the Input</button>
</div>
Syntax Breakdown:
DIV element:
x-data directive: Initialize Alpine component state.
Value: JavaScript object { focusInput() { $refs.myInput.focus(); } }
- focusInput: state property (method).
- Accesses the element referenced as 'myInput' via the magic $refs object.
- Calls the element's native '.focus()' method.
INPUT element (type="text"):
x-ref directive: Assign a reference name to this DOM element.
Value: 'myInput'. Makes element accessible via $refs.myInput within the component.
BUTTON element:
@click directive: Add click event listener.
Value: Execute component method 'focusInput()'.
$refs holds all the elements that have been given a reference name.
3.9 x-transition#
What it does:
Adds transition effects for elements entering or leaving the DOM when using directives like x-show.
When to use it:
Use x-transition to create smooth animations when toggling the display of an element. You can also customize enter/leave transitions.
Example:
<div x-data="{ open: false }">
<button @click="open = !open">Toggle</button>
<div x-show="open" x-transition>
<p>This content fades in and out.</p>
</div>
</div>
Syntax Breakdown:
DIV element:
x-data directive: Initialize Alpine component state.
Value: JavaScript object { open: false }
- open: state property, initial value false
BUTTON element:
@click directive: Add click event listener.
Value: Execute JavaScript 'open = !open' (toggle boolean state property 'open').
DIV element:
x-show directive: Conditionally toggle element's visibility.
Value: Evaluate boolean state property 'open'.
x-transition directive: Apply default CSS transitions on show/hide triggered by x-show.
For more advanced transitions, you can define classes for different phases:
<div x-show="open"
x-transition:enter="transition ease-out duration-300"
x-transition:enter-start="opacity-0 transform scale-90"
x-transition:enter-end="opacity-100 transform scale-100"
x-transition:leave="transition ease-in duration-200"
x-transition:leave-start="opacity-100 transform scale-100"
x-transition:leave-end="opacity-0 transform scale-90">
<p>Animated content here.</p>
</div>
Syntax Breakdown:
DIV element:
x-show directive: Conditionally toggle element's visibility.
Value: Evaluate boolean state property 'open'.
x-transition:enter directive: Define classes applied during the entire enter transition.
Value: CSS classes 'transition ease-out duration-300'.
x-transition:enter-start directive: Define classes applied at the beginning of the enter transition.
Value: CSS classes 'opacity-0 transform scale-90'.
x-transition:enter-end directive: Define classes applied at the end of the enter transition.
Value: CSS classes 'opacity-100 transform scale-100'.
x-transition:leave directive: Define classes applied during the entire leave transition.
Value: CSS classes 'transition ease-in duration-200'.
x-transition:leave-start directive: Define classes applied at the beginning of the leave transition.
Value: CSS classes 'opacity-100 transform scale-100'.
x-transition:leave-end directive: Define classes applied at the end of the leave transition.
Value: CSS classes 'opacity-0 transform scale-90'.
Reply by Email