axios-form-handler

A form handling library inspired by Inertia.js useForm, with Axios integration for seamless API requests and Laravel validation support.

Features

🚀 Inertia.js-like API: Familiar useForm interface for developers coming from Inertia.js
🔧 TypeScript Support: Full TypeScript support with type definitions
🌐 Axios Integration: Built-in HTTP client integration
✅ Laravel Validation: Automatic Laravel validation error handling (422 responses)
🔄 State Management: Built-in form state management (processing, errors, fields)
📦 Framework Agnostic: Works with React, Vue, Alpine.js, or vanilla JS/TS
🎯 Lightweight: Minimal dependencies, maximum functionality

Installation

npm install axios-form-handler

yarn add axios-form-handler

pnpm add axios-form-handler

Why axios-form-handler?

If you love the simplicity of Inertia.js useForm but need to use it with traditional APIs or in non-Inertia applications, this library is for you! It provides the same intuitive form handling experience with:

Laravel-ready: Automatically handles Laravel validation responses (422 status codes)
Familiar API: Same method names and behavior as Inertia.js useForm
Universal compatibility: Works in any JavaScript/TypeScript environment
Axios powered: Leverages the popular Axios HTTP client

Perfect for developers building SPAs or Alpine.js with Laravel backends, migrating from Inertia.js, or anyone who wants Laravel-style form validation in their frontend applications.

Quick Start

import { useForm } from 'axios-form-handler';

// Create a form instance (just like Inertia.js!)
const form = useForm({
  name: '',
  email: '',
  message: ''
});

// Submit the form to your Laravel API
form.post('/api/contact', {
  onSuccess: (data) => {
    console.log('Form submitted successfully:', data);
  },
  onValidationErrors: (errors) => {
    // Laravel validation errors automatically parsed
    console.log('Validation errors:', errors);
  },
  onError: (error) => {
    console.log('Request failed:', error);
  }
});

Laravel Backend Integration

This library is designed to work seamlessly with Laravel's validation system:

// Laravel Controller
public function store(Request $request)
{
    $request->validate([
        'name' => 'required|string|max:255',
        'email' => 'required|email',
        'message' => 'required|string'
    ]);
    
    // Your logic here...
    
    return response()->json(['message' => 'Success!']);
}

When validation fails, Laravel returns a 422 status code with errors in this format:

{
    "errors": {
        "email": ["The email field is required."],
        "name": ["The name field is required."]
    }
}

The library automatically catches these errors and populates the form.errors object!

API Reference

`useForm(fields)`

Creates a new form instance with the specified fields.

Parameters:

fields (Record<string, any>): Initial form field values

Returns: FormInstance

Form Methods

`post(route, options?)`

Submit form data via POST request.

`put(route, options?)`

Submit form data via PUT request.

`patch(route, options?)`

Submit form data via PATCH request.

`delete(route, options?)`

Submit form data via DELETE request.

`reset()`

Reset form to initial values and clear errors.

`clearErrors()`

Clear all validation errors.

`setError(key, message)`

Set validation error for a specific field.

Response Options

interface ResponseOption {
  onSuccess?: (data: Record<any, any>) => void;
  onValidationErrors?: (data: Record<any, any>) => void;
  onError?: (error: AxiosError) => void;
  onFinish?: () => void;
}

Form Properties

fields: Access to all form field values
errors: Current validation errors
processing: Boolean indicating if request is in progress
hasErrors: Boolean indicating if form has validation errors

Advanced Usage

Custom Axios Instance

import axios from 'axios';
import { setFormAxios } from 'axios-form-handler';

// Create custom axios instance
const api = axios.create({
  baseURL: 'https://api.example.com',
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

// Set as default for all forms
setFormAxios(api);

Working with Form Fields

const form = useForm({
  username: 'john_doe',
  email: 'john@example.com'
});

// Access field values
console.log(form.username); // 'john_doe'
console.log(form.fields); // { username: 'john_doe', email: 'john@example.com' }

// Update field values
form.username = 'jane_doe';
form.email = 'jane@example.com';

// Check for errors
if (form.hasErrors) {
  console.log(form.errors);
}

Laravel Validation Error Handling

The library automatically handles Laravel-style validation errors (422 status code) exactly like Inertia.js:

const form = useForm({ 
  email: '', 
  password: '' 
});

form.post('/api/login', {
  onValidationErrors: (errors) => {
    // Laravel validation errors are automatically parsed
    console.log(errors.email);    // "The email field is required"
    console.log(errors.password); // "The password field is required"
  }
});

// Access errors directly on the form object
if (form.hasErrors) {
  console.log(form.errors.email); // Direct access to field errors
}

Laravel Response Format (422 status):

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

Parsed Form Errors:

form.errors = {
  email: "The email field is required.",
  password: "The password must be at least 8 characters."
}

Loading States

const form = useForm({ name: '', email: '' });

form.post('/api/contact', {
  onFinish: () => {
    // This runs whether the request succeeds or fails
    console.log('Request completed');
  }
});

// Check processing state
if (form.processing) {
  console.log('Form is being submitted...');
}

Migration from Inertia.js

If you're migrating from Inertia.js or want to use the same patterns, the API is nearly identical:

Inertia.js

import { useForm } from '@inertiajs/react'

const form = useForm({
  name: '',
  email: '',
})

form.post('/users', {
  onSuccess: () => alert('Success!'),
})