Core Concepts - Alpine.js

Alpine.js is a minimalistic client-side JavaScript framework designed to provide reactive and declarative functionality in your web projects without the overhead of larger frameworks.

TIP

Alpine.js offers more functionality beyond what is covered on this page. For a comprehensive guide to all directives, as well as features like Magic properties, Global APIs, and Plugins, refer to the official documentation. There, you'll also find more detailed explanations and advanced usage examples.

Installation

When using the TALL-stack you don't have to worry about the installation of Alpine as it is already included when using the correct setup. Do you want to use Alpine in a different project? Simply include the following script tag in the head of your HTML page:

<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

Directives

x-data

The x-data directive defines a chunk of HTML as an Alpine.js component and provides reactive data for it. This data is accessible to all child elements, even within nested components, unless overridden by another x-data.

Documentation

Example:

<div x-data="{ foo: 'bar' }">
    <span x-text="foo"><!-- Will output: "bar" --></span>
 
    <div x-data="{ bar: 'baz' }">
        <span x-text="foo"><!-- Will output: "bar" --></span>
 
        <div x-data="{ foo: 'bob' }">
            <span x-text="foo"><!-- Will output: "bob" --></span>
        </div>
    </div>
</div>

x-text

The x-text directive updates an element’s text content with the value of a given expression, keeping it reactive.

Documentation

Example:

<div x-data="{ message: 'Hello, Alpine!' }">
    <span x-text="message"></span>
</div>

x-model

The x-model directive binds the value of an input element to a data property, enabling two-way data binding. Changes to the input update the data property, and updates to the data property reflect in the input.

<div x-data="{ name: '' }">
    <input x-model="name" placeholder="Enter your name">
    <p>Hello, <span x-text="name"></span>!</p>
</div>

x-on / @

The x-on directive is used to attach event listeners to elements in Alpine.js. It allows you to respond to user interactions, such as clicks or input changes, by executing a specified expression or function. You can also use the @ symbol as a shorthand for x-on.

<div x-data="{ count: 0 }">
    <button x-on:click="count++">Increment</button>
    <!-- or using shorthand -->
    <button @click="count++">Increment</button>
    <p>Count: <span x-text="count"></span></p>
</div>

x-show

The x-show directive conditionally displays an element based on the truthiness of an expression. When the expression evaluates to true, the element is shown; when false, it is hidden.

<div x-data="{ isVisible: true }">
    <button @click="isVisible = !isVisible">Toggle Visibility</button>
    <p x-show="isVisible">This paragraph is conditionally visible.</p>
</div>

x-cloak

The x-cloak directive hides an element until Alpine.js has fully initialized. This ensures that the element remains invisible while Alpine.js processes the directives, preventing any initial display issues.

<div x-data="{ show: false }" x-cloak>
    <button @click="show = !show">Toggle Content</button>
    <p x-show="show">This content is controlled by Alpine.js.</p>
</div>

Without x-cloak in the example above, the div might briefly appear visible to the user (before Alpine.js initializes).

x-for

The x-for directive in Alpine.js is used to iterate over an array or object and generate a set of elements based on each item. It works similarly to a loop, allowing you to dynamically create HTML elements based on data.

WARNING

x-for MUST be declared on a <template> element. That <template> element MUST contain only one root element

The :key attribute is also needed as it uniquely identifies each list item, allowing Alpine.js to update and manage the list correctly. Without it, items might not update properly, causing rendering issues.

<div x-data="{ items: ['Apple', 'Banana', 'Cherry'] }">
    <ul>
        <template x-for="item in items" :key="item">
            <li x-text="item"></li>
        </template>
    </ul>
</div>