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

``bash
npm install axios-form-handler
`

`bash
yarn add axios-form-handler
`

`bash
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

`typescript
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:

`php
// 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:
`json
{
"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

$3

Creates a new form instance with the specified fields.

Parameters:
- fields (Record): Initial form field values

Returns: FormInstance

$3

#### 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.

$3

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

$3

- 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

$3

`typescript
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);
`

$3

`typescript
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);
}
`

$3

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

`typescript
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):
`json
{
"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:
`javascript
form.errors = {
email: "The email field is required.",
password: "The password must be at least 8 characters."
}
`

$3

`typescript
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:

$3

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

$3

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

The main differences:
- Add /api prefix to your routes (or configure Axios base URL)
- Import from axios-form-handler instead of @inertiajs/react
- Optionally configure custom Axios instance for authentication

$3

`js

import Alpine from 'alpinejs';
import axios from 'axios';
import { setFormAxios, useForm } from 'axios-form-handler';

axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
axios.defaults.headers.common['X-CSRF-Token'] = document.querySelector('meta[name="csrf_token"]').getAttribute('content');

setFormAxios(axios);

document.addEventListener('alpine:init', () => {
Alpine.data('form', (route) => ({
route,

init() {
this.form = useForm({
first_name: '',
last_name: '',
email: '',
});
},

onSubmit() {
this.form.post(route, {
onSuccess: (data) => {
alert('Message sent successfully!');
form.reset();
},
});
},
}));
});
`
`html


Contributing

Please, submit bugs or feature requests via the Github issues.

Pull requests are welcomed!

Thanks!

License

This project is open-sourced software licensed under the MIT License.

You are free to use, modify, and distribute it in your projects, as long as you comply with the terms of the license.

---

Maintained by ISAPP and ISAP OÜ.
Check out our software development services at isap.me.