Writing Alpine.js directives?

Alpine directives not reacting the way you expect? We clear it up.

Alpine.js is deliberately small, and that is its strength and its trap. A handful of directives sprinkled on your HTML buys you a reactive UI without a build step; sprinkle them wrong and you get scopes that nest where you did not intend, x-for lists that lose state on every render, and $store updates that silently fail to redraw. We work through the Alpine graph until the DOM reacts the way the markup promises.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

alpine-console.log

still failing

What it is

Alpine.js at a glance

Alpine.js is a lightweight JavaScript framework for sprinkling reactive behavior onto HTML without a build pipeline. It was created by Caleb Porzio in 2019 and is often described as 'Tailwind for JavaScript': a set of small directives like x-data, x-show, x-for and x-on that you drop into markup, with a reactivity engine small enough to ship over the wire inline.

It is used heavily alongside server-rendered frameworks like Laravel Livewire, Phoenix LiveView, Rails Hotwire and HTMX, where the server returns HTML and Alpine handles the small bits of client state like dropdowns, modals and tabs. The library is around 15kB gzipped, ships components through Alpine.data and shared state through Alpine.store, and has a small plugin ecosystem for routing, persistence and animations.

Type
Lightweight declarative JavaScript framework
First released
2019 initial public release
License
MIT, free and permissive
Maintained by
Caleb Porzio and community contributors
Typically used for
Interactive HTML on top of server-rendered apps, dropdowns and modals, Livewire and HTMX enhancements

The honest version

Alpine.js pros and cons

No technology is all upside. This is where Alpine.js earns its place and where it tends to cause trouble.

Where Alpine.js is strong

  • No build step requiredA single script tag in the head and you can write reactive HTML. You skip webpack, Vite, bundler config and the whole node_modules story.
  • Reads like HTMLx-show, x-for and x-on map one-to-one onto DOM behavior you would write anyway. New team members pick it up without a training week.
  • Small payloadAround 15kB over the wire is a rounding error compared to shipping a full React or Vue runtime for a marketing site with three dropdowns.
  • Pairs well with HTMX and LivewireAlpine fills the client-state gap that HTMX and Livewire leave open, and the combined pattern lets most apps skip a full SPA.
  • Components and stores without ceremonyAlpine.data registers reusable components and Alpine.store gives you cross-component state, both without a module bundler or a reactive library.

Where Alpine.js bites

  • Scope nesting is easy to get wrongEvery x-data creates a new scope, and inner scopes shadow outer ones. A nested component unintentionally shadowing a parent property is the single biggest source of 'why does this not update' tickets.
  • Error messages are shallowAlpine expression errors tell you the expression failed, not the component tree it failed in. Tracking down which x-data owns a broken binding is manual on a large page.
  • x-for keys are mandatory in practiceLists without a stable :key lose component state on every reorder. The docs mention this; teams still forget, and the symptoms look like reactivity bugs rather than key bugs.
  • Hits a wall on anything complexOnce you need routing, serious composition, SSR hydration or shared state across many components, Alpine starts to feel limiting and the usual answer is to drop in Vue or Svelte.
  • Livewire morph collisionsWhen a Livewire morph swaps DOM out from under Alpine, nested state can be lost or duplicated unless x-persist and keys are set correctly, which is hard to debug when it happens.
  • Plugin ecosystem is thinThe core plugins cover persistence, intersection and mask, but anything beyond that is community-maintained and often one person's side project.

Sound familiar?

Common Alpine.js problems we fix

The Alpine.js problems that bring people to us, and what you have once each one is fixed.

x-for: duplicate keys detected

Lists lose state on reorder or filter

Items missing a stable :key, or a key that is actually the index rather than the item id, cause Alpine to reuse the wrong DOM nodes. We assign a real unique key and the list behaves correctly across updates.

Lists keep their state

nested x-data shadowed parent variable

Child component cannot see the parent store

A nested x-data declared a local 'cart' that shadowed the parent. We rename the local scope, or lift the shared state to Alpine.store so there is one source of truth across the page.

Child reads the right state

x-model not updating nested property

Two-way binding does not fire on object fields

Alpine's reactivity watches properties that existed at init time. Properties added later are not reactive unless the whole object is replaced. We shape the initial data correctly or use Alpine.reactive explicitly.

Bindings fire as expected

Alpine.store('cart') undefined

A store is missing or initialised late

Code runs before Alpine.store() has been declared, usually because the store script is loaded after the component. We move store declarations to alpine:init and gate access on the ready event.

Stores available before components mount

$dispatch event never received

Custom events fire without being heard

An x-on listener bound on the wrong element, or a stopped event bubble from a parent. We trace the event path in devtools and attach the listener on an element that actually sees the event.

Events arrive where expected

Livewire morph collision on component

Alpine state is lost on a Livewire update

A Livewire re-render replaces DOM Alpine was managing, losing local state. We add x-persist, stable keys, and move anything important to Alpine.store so morph does not destroy the data.

State survives Livewire updates

x-cloak flashed before Alpine ready

Content flashes unstyled before hydration

The x-cloak attribute is declared but the matching CSS rule is missing, so the UI flashes before Alpine hides it. We add the display:none rule for x-cloak and the flash is gone.

No more unstyled flicker

What we do

Alpine.js help, from stuck directives to Livewire plumbing

Call us for one misbehaving component, or let us audit the whole Alpine layer.

Rescue
Reactivity bugs, shadowed scopes, broken x-for lists and Livewire morph collisions diagnosed and fixed.
Component refactors
Inline x-data cleaned into Alpine.data components, with a sensible store layout so cross-component state stops bleeding.
Livewire and HTMX integration
Morph-safe Alpine components with the right x-persist and key patterns, so server updates do not erase client state.
Performance review
Reactive graph audited for expensive expressions, large x-for lists moved to virtualised patterns, and x-cloak set up so the first paint is clean.
Managed Tech
Ongoing upkeep as Alpine releases new versions, plugin upgrades, and a US engineer to call when Livewire or Alpine ships a change that affects your templates.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Alpine.js alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Alpine.js questions

Something else? Call+1 737 727 7327

Why is my Alpine component not reacting to data changes?

Three usual causes. First, the property was added to the data object after Alpine initialised, which makes it non-reactive. Second, a nested x-data is shadowing the property you think you are updating. Third, the update is happening on a cloned object rather than the live one, usually because of spread syntax in a handler. We trace which component actually owns the property and fix the mutation to hit it.

Should I always set :key on x-for?

Yes, and the key should be a stable identifier for the item, not its position in the list. Alpine reuses DOM nodes between renders, and without a stable key it binds the wrong node to the wrong item after a sort or filter. Index keys look like they work in dev and fall apart the moment the list reorders.

How does Alpine.js work with Livewire?

Livewire owns the server-rendered DOM and Alpine owns the local client state inside it. The friction is that Livewire's morph can replace nodes Alpine was managing. The fix is x-persist on components whose state should survive a morph, stable keys on lists, and Alpine.store for anything shared across components so the data is not tied to a single node.

When should I stop using Alpine and switch to Vue or Svelte?

When your app needs routing, serious component composition, SSR hydration, or shared state across more than a handful of components. Alpine is designed to sprinkle interactivity onto server-rendered HTML. If you are reaching for a global router and component library, you are building an SPA, and a framework designed for SPAs will cost less in the long run.

How much does Alpine.js help cost?

The quote is free. Send us the page or the component that is misbehaving, and a US engineer will reply with a fixed price for the work before anything starts.

Free estimate

Alpine.js giving you trouble?

Send over the markup and the symptom, and a US engineer will reply with a plan and a price for the fix.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.