alpine

name: alpine description: Use when working with Alpine.js directives, components, reactivity, or client-side behavior in Phlex views or public/js/app.js

Alpine.js

Lightweight reactive framework. Declares behavior inline via HTML directives. No build step - loaded via CDN with SRI hashes in views/layout.rb.

Version: 3.15.8 (core), 3.15.0 (persist plugin).

Source: https://alpinejs.dev

Directives

Magic Properties

Globals

Register components and stores inside alpine:init:

document.addEventListener("alpine:init", () => {
    Alpine.data("dropdown", () => ({
        open: false,
        toggle() { this.open = !this.open },
        init() { /* auto-called on mount */ },
        destroy() { /* auto-called on removal */ },
    }))

    Alpine.store("darkMode", {
        on: false,
        init() { /* runs after registration */ },
        toggle() { this.on = !this.on },
    })

    Alpine.bind("SomeButton", () => ({
        type: "button",
        ["@click"]() { this.doSomething() },
        [":disabled"]() { return this.shouldDisable },
    }))
})

Alpine.data() components accept parameters: x-data="dropdown(true)".

Access magic properties via this inside Alpine.data(): this.$watch(...), this.$refs, etc.

Access stores outside Alpine: Alpine.store("darkMode").toggle().

x-data

Inline object or registered name. Methods, getters, init(), and destroy() all supported. Inner x-data scopes shadow outer properties.

<div x-data="{ open: false, toggle() { this.open = !this.open } }">
    <button @click="toggle">Toggle</button>
    <div x-show="open">Content</div>
</div>

Empty component: x-data or x-data="{}".

x-bind Class and Style

<!-- Ternary -->
<div :class="open ? 'visible' : 'hidden'">

<!-- Object syntax (preserves original classes) -->
<div :class="{ 'hidden': !show, 'active': isActive }">

<!-- Short-circuit -->
<div :class="closed && 'hidden'">

<!-- Style object -->
<div :style="{ color: 'red', display: 'flex' }">

x-on Modifiers

Keyboard: .enter, .escape, .space, .tab, .shift, .ctrl, .cmd, .alt, .meta, .up, .down, .left, .right. Other keys in kebab-case (.page-down). Chainable: @keyup.shift.enter.

x-model Modifiers

Combinable: .blur.enter syncs on both events.

Programmatic access: el._x_model.get() / el._x_model.set(value).

x-for

Must use <template>. Single root element inside.

<template x-for="item in items" :key="item.id">
    <li x-text="item.name"></li>
</template>

<!-- With index -->
<template x-for="(item, index) in items">
    <li x-text="index + ': ' + item.name"></li>
</template>

<!-- Range -->
<template x-for="i in 10">
    <span x-text="i"></span>
</template>

x-transition

Apply to same element as x-show.

<!-- Default: fade + scale, 150ms enter, 75ms leave -->
<div x-show="open" x-transition>

<!-- Modifiers -->
<div x-show="open" x-transition.opacity.duration.300ms>
<div x-show="open" x-transition.scale.80.origin.top>

<!-- CSS classes for full control -->
<div x-show="open"
     x-transition:enter="transition ease-out duration-300"
     x-transition:enter-start="opacity-0 scale-90"
     x-transition:enter-end="opacity-100 scale-100"
     x-transition:leave="transition ease-in duration-150"
     x-transition:leave-start="opacity-100 scale-100"
     x-transition:leave-end="opacity-0 scale-90">

Persist Plugin

Wraps values for automatic localStorage persistence across page reloads.

// Basic
{ count: $persist(0) }

// Custom key
{ count: $persist(0).as("my-count") }

// Session storage (clears on tab close)
{ count: $persist(0).using(sessionStorage) }

// In Alpine.data(), use regular function for this.$persist
Alpine.data("dropdown", function () {
    return { open: this.$persist(false) }
})

// In stores
Alpine.store("darkMode", {
    on: Alpine.$persist(true).as("darkMode_on"),
})

Patterns in This Project

Phlex Keyword Arguments

Phlex views pass Alpine directives as Ruby keyword arguments with string keys:

div("x-data": "{ editing: false }") do
  button("x-show": "!editing", "x-on:click": "editing = true")
  div("x-show": "editing", "x-cloak": true)
end

Component Registration

All reusable components are registered in public/js/app.js inside the alpine:init listener. Components used: intervalEditor, dueDateEditor, historyNote, completedDateEditor.

Object Spread for Multiple Components

Merge multiple registered components on one element:

div("x-data": "{ ...historyNote(#{series_id}, #{task_id}, #{has_note}), ...completedDateEditor(#{series_id}, #{task_id}, '#{date}') }")

x-show + x-cloak

Pair x-cloak with x-show on initially-hidden elements to prevent flash of content before Alpine initializes.

Custom Events

$dispatch('start-editing') / $dispatch('stop-editing') for communication between the edit section scope and panel editors in app.js.

init() Is a Lifecycle Hook

init() inside x-data or Alpine.data() auto-runs on mount. Do not use init as a regular method name — it will fire unexpectedly.