Alpine.js x-data Directive — Complete Guide with Examples

In this tutorial, you'll learn about the Alpine.js x-data directive. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

The Alpine.js x-data directive is the foundation of every Alpine component, defining reactive state that the framework watches for changes and automatically updates in the DOM.

What You'll Learn

By the end of this tutorial, you'll understand how to declare reactive state with x-data, nest components, share data between them, and initialize complex state objects like arrays and nested objects.

Why It Matters

Every interactive Alpine component starts with x-data. Without it, Alpine has no boundary to observe and no reactive state to manage. Mastering x-data means you control exactly how and where interactivity lives on your page.

Real-World Use

A real estate listing page uses nested x-data components: a parent component holds the search filters, and each property card is its own child component with independent state for expanded details. This keeps the UI modular and performant.

Where This Fits in Your Learning Path

flowchart LR
    A["HTML & JavaScript Basics"] --> B["**x-data Directive**"]
    B --> C["x-bind & x-on"]
    C --> D["x-model & Forms"]
    D --> E["Advanced Alpine Patterns"]
    style B fill:#f97316,stroke:#c2410c,color:#fff
    style A fill:#e5e7eb,stroke:#9ca3af,color:#374151
    style E fill:#22c55e,stroke:#16a34a,color:#fff

What is x-data?

The x-data directive is Alpine's way of saying "this is a reactive component." You pass a JavaScript object to it, and Alpine tracks every property inside that object for changes.

Think of x-data like a workshop bench. You lay out your tools (state variables) on the bench, and Alpine stands nearby watching. Whenever you pick up a tool or move it, Alpine notices and updates anything on the page that depends on that tool.

<div x-data="{ isOpen: false, count: 0 }">
  <p>Count: <span x-text="count"></span></p>
  <p>Open: <span x-text="isOpen"></span></p>
  <button @click="count++">Increment</button>
</div>

Expected output: "Count: 0" and "Open: false" displayed. Clicking the button increments the count.

Declaring Simple State

The simplest x-data declaration uses primitive values: strings, numbers, and booleans.

<div x-data="{ name: 'Alice', age: 30, isLoggedIn: false }">
  <p>Name: <span x-text="name"></span></p>
  <p>Age: <span x-text="age"></span></p>
  <p x-show="isLoggedIn">Welcome back!</p>
</div>

Expected output: "Name: Alice" and "Age: 30" displayed. The welcome message is hidden because isLoggedIn is false.

Declaring Complex State

x-data also supports arrays and nested objects. Alpine tracks nested changes through JavaScript Proxies.

<div x-data="{ users: ['Alice', 'Bob'], scores: { alice: 95, bob: 87 } }">
  <p x-text="users.length"></p>
  <p x-text="scores.alice"></p>
  <button @click="users.push('Charlie')">Add Charlie</button>
</div>

Expected output: "2" for the user count, "95" for Alice's score. Clicking the button adds Charlie and the count updates to 3.

Nesting Components

x-data components can be nested. Each component has its own isolated scope. A child component can access parent data through Alpine's scope inheritance.

<div x-data="{ parentMessage: 'Hello from parent' }">
  <p x-text="parentMessage"></p>
  <div x-data="{ childMessage: 'Hello from child' }">
    <p x-text="parentMessage"></p>
    <p x-text="childMessage"></p>
  </div>
</div>

Expected output: Both components show the parent message. The child also shows its own message. The child CAN read parentMessage because Alpine resolves variables by walking up the scope chain.

Common Mistakes

1. Forgetting quotes around the attribute value

<!-- Wrong: missing quotes, will cause parse error -->
<div x-data={count: 0}>

<!-- Correct: quotes around the entire object -->
<div x-data="{ count: 0 }">

2. Using semicolons instead of commas

<!-- Wrong: semicolons are not valid in JavaScript objects -->
<div x-data="{ count: 0; name: 'Alice' }">

<!-- Correct: commas between properties -->
<div x-data="{ count: 0, name: 'Alice' }">

3. Mutating arrays by index without reassignment

<!-- Wrong: items[0] = 99 may not trigger reactivity -->
<button @click="items[0] = 99">

<!-- Correct: use reassignment or array methods like splice -->
<button @click="items = [99, ...items.slice(1)]">

4. Defining the same property name in nested components unintentionally

When a child component defines a property with the same name as a parent, the child's property shadows the parent's. This can cause confusing bugs.

5. Using undefined variables inside x-data

Every variable used in x-data expressions must be declared. If you reference a variable that doesn't exist in the current or parent scope, Alpine throws an error.

Practice Questions

1. What does the x-data directive do? It declares a reactive Alpine component by defining its initial state as a JavaScript object. Alpine tracks all properties for changes and updates the DOM automatically.

2. Can you nest x-data components? Yes. Nested components have their own isolated scope but can access parent properties through Alpine's scope chain.

3. What happens if you mutate an array by index? The change may not trigger reactivity. Use array methods like push, splice, or reassign the entire array.

4. What types of values can x-data hold? Any JavaScript value: strings, numbers, booleans, arrays, objects, functions, and even promises.

5. Is x-data required for every Alpine component? Yes. Every Alpine component must have x-data to define its reactive boundary. Even empty x-data works.

Challenge

Build a nested x-data component tree: a parent that holds a shopping cart array, and child components for each cart item with independent quantity controls. The parent should display the total item count.

FAQ

Mini Project

Build a product comparison tool with three nested x-data components. The parent holds the list of products and the selected comparison features. Each child product card has its own expanded/collapsed state.

<div x-data="{ products: ['Laptop', 'Tablet', 'Phone'], selected: [] }">
  <h2>Compare Products</h2>
  <template x-for="product in products" :key="product">
    <div x-data="{ expanded: false }">
      <h3 x-text="product"></h3>
      <button @click="expanded = !expanded" x-text="expanded ? 'Collapse' : 'Expand'"></button>
      <div x-show="expanded">
        <p>Details about <span x-text="product"></span></p>
        <button @click="$dispatch('select', { product })">Select for comparison</button>
      </div>
    </div>
  </template>
  <p>Selected: <span x-text="selected.join(', ')"></span></p>
</div>

What's Next

Now that you understand x-data, continue with related topics:

Related topics: JavaScript objects and reactivity, Vue.js data() comparison.