Alpine-Forms — Making form validation, state management, and submission effortless in Alpine.js

[mhsiddiqui]

Alpine-Forms 🚀

A lightweight Alpine.js plugin that brings high-level form management and validation to the Alpine.js ecosystem. Handle state, validation, and submissions declaratively—without the boilerplate.

---

🔴 The Problem

Standard Alpine.js forms often require manual tracking of:

• Field "touched" and "dirty" states.
• Validation logic and error message toggling.
• Loading states during async submissions.
• Server-side error mapping.

🟢 The Solution

Alpine-Forms provides an Alpine.Form() factory and an x-register directive to automate your form workflow.

Quick Example

<div x-data="{
      form: Alpine.Form(
          { email: '', password: '' },
          {
              config: {
                  validations: {
                      email: (v) => !v ? { message: 'Email is required' } : undefined,
                      password: (v) => v.length < 6 ? { message: 'Min 6 characters' } : undefined,
                  }
              }
          }
      )
  }">
    <form @submit.prevent="form.submit(data => console.log(data))">
        <div>
            <input x-register:form="form.field('email')" type="email" placeholder="Email" />
            <span x-show="!form.getFieldState('email').isValid"
                  x-text="form.getFieldState('email').error" 
                  style="color: red;"></span>
        </div>

        <div>
            <input x-register:form="form.field('password')" type="password" placeholder="Password" />
            <span x-show="!form.getFieldState('password').isValid"
                  x-text="form.getFieldState('password').error" 
                  style="color: red;"></span>
        </div>

        <button type="submit" :disabled="form.getFormState().isSubmitting">
            <span x-show="!form.getFormState().isSubmitting">Submit</span>
            <span x-show="form.getFormState().isSubmitting">Processing...</span>
        </button>
    </form>
</div>

Features

• State Tracking: Real-time tracking of isDirty, isTouched, isValid, and isSubmitting.
• Validation Modes: Choose between onChange, onBlur, onTouched, or onSubmit.
• Schema Support: Built-in compatibility for Joi and Zod.
• Async Validation: Perfect for "Username available" API checks with built-in race condition handling.
• Server-Side Integration: Use setError() to map API errors back to specific fields.
• Partial Updates: Use getDirtyFields() to send only changed data to your backend.
• Auto-Focus: Automatically moves cursor to the first invalid field on failed submission.

Installation

CDN (Zero Config)

Include the script before your Alpine.js core script. It auto-registers on alpine:init.

<script defer src="https://unpkg.com/alpine-forms/dist/alpine.forms.min.js"></script>
<script defer src="https://unpkg.com/alpinejs"></script>

npm

npm install alpine-forms

import Alpine from 'alpinejs';
import { directives } from 'alpine-forms';

Alpine.plugin(directives);
Alpine.start();

Documentation & Resources

Live Demos: mhsiddiqui.github.io/alpine-forms
npm Package: alpine-forms
GitHub Repository: mhsiddiqui/alpine-forms

Contributing

Feedback and pull requests are welcome! If you find a bug or have a feature request, please open an issue on the GitHub repository.