Alpinejs Django

Alpine.js with Django

Use this skill for local browser state in Django-rendered templates: dropdowns, modals, tabs, disclosures, inline filters, disabled/loading states, small preview interactions, and client-only toggles. Use Django views/forms/models as the source of truth for durable state. Use HTMX when the server needs to return fresh HTML.

Setup checks

• Identify how the project loads Alpine. Prefer the existing static asset or bundling pipeline as the source of truth.
• Find the base template, layout, or bundled entrypoint that loads HTMX, Alpine, and app JavaScript. Preserve the current ordering unless changing initialization deliberately.
• Determine whether the loaded Alpine file is self-starting or module-based. Do not call Alpine.start() when the project already loads a self-starting Alpine build. If using a module build, register components and start Alpine from the owning entrypoint.
• Simple Alpine behavior should usually live inline in the Django template with x-data.
• If a reusable component or store is worth extracting, register it before Alpine starts. Check the existing script order before relying on document.addEventListener("alpine:init", ...) from an app-wide script.
• When reusable Alpine registration is needed, add or reuse a script or entrypoint that runs before Alpine starts. Register components and stores inside document.addEventListener("alpine:init", ...), include the file through the project's normal asset path, and avoid double-starting Alpine.

Ownership rules

• Django owns persistence, authorization, validation, redirects, and rendered HTML.
• HTMX owns server round trips and DOM swaps.
• Alpine owns ephemeral state already present in the browser.
• Plain JavaScript modules or bundled entrypoints own shared DOM behavior that is not naturally scoped to one Alpine component.
• Do not duplicate the same behavior in Alpine and a plain JS module.

Template patterns

Use a small x-data object near the markup it controls:

<div
  x-data="{ open: false }"
  @keydown.escape.window="open = false"
  @click.outside="open = false"
>
  <button
    type="button"
    :aria-expanded="open.toString()"
    @click.stop="open = !open"
  >
    Menu
  </button>

  <div x-cloak x-show="open" x-transition>
    ...
  </div>
</div>

Prefer Alpine directives over manual DOM manipulation:

• x-show for toggling visibility while keeping the element in the DOM.
• x-if on a <template> when the element should be created and destroyed.
• x-model for client-only input state; Django form submission and validation still happen on the server.
• :class, :disabled, :aria-expanded, and :hidden for state-derived attributes.
• $watch for one named state transition; x-effect only when the dependency set is simple and intentional.
• $dispatch for browser events between Alpine components or from Alpine to HTMX triggers.

Use x-cloak for anything hidden by default. Ensure the base CSS includes the required [x-cloak] { display: none !important; } rule.

Django data

Keep Django interpolation out of complex JavaScript expressions when possible.

For simple values, prefer HTML attributes:

<div
  data-initial-label="{{ object.name }}"
  x-data="{ label: '' }"
  x-init="label = $el.dataset.initialLabel"
>
  <span x-text="label"></span>
</div>

For structured values, prefer Django's json_script and parse it in x-init:

{{ rows|json_script:"rows-data" }}

<div
  x-data="{ rows: [] }"
  x-init="rows = JSON.parse(document.getElementById('rows-data').textContent)"
>
  <template x-for="row in rows" :key="row.id">
    <span x-text="row.name"></span>
  </template>
</div>

Avoid |safe inside Alpine expressions. If the browser must display text, use x-text. Use x-html only for trusted, already-sanitized HTML; most HTML should be rendered by Django or returned through HTMX.