@wuild/vue-forms

A lightweight Vue 3 plugin for easy form handling with validation and error management.

Installation

npm install @wuild/vue-forms
# or
yarn add @wuild/vue-forms

Features

• 🚀 Simple form state management
• ✅ Built-in validation error handling
• 🔄 Form reset and dirty state tracking
• 📊 Form submission with progress tracking
• 🛡️ TypeScript support

Usage

Global Registration

// main.js or main.ts
import { createApp } from 'vue'
import { FormPlugin } from '@wuild/vue-forms'
import App from './App.vue'

const app = createApp(App)
app.use(FormPlugin)
app.mount('#app')

Basic Usage with Composition API

<template>
  <form @submit.prevent="form.submit(handleSubmit)">
    <div>
      <label for="name">Name:</label>
      <input id="name" v-model="form.name" type="text" />
      <div v-if="form.errors.name" class="error">
        {{ form.errors.name[0] }}
      </div>
    </div>

    <div>
      <label for="email">Email:</label>
      <input id="email" v-model="form.email" type="email" />
      <div v-if="form.errors.email" class="error">
        {{ form.errors.email[0] }}
      </div>
    </div>

    <button type="submit" :disabled="form.processing">
      {{ form.processing ? 'Submitting...' : 'Submit' }}
    </button>

    <div v-if="form.progress !== null">
      Upload progress: {{ form.progress }}%
    </div>
  </form>
</template>

<script setup>
import { useForm } from '@wuild/vue-forms'

// Initialize form with default values
const form = useForm({
  name: '',
  email: ''
})

// Form submission handler
const handleSubmit = async (data) => {
  try {
    // Send data to your API
    const response = await fetch('/api/submit', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    })

    if (!response.ok) {
      const errorData = await response.json()
      throw { response: { data: errorData } }
    }

    // Handle successful submission
    alert('Form submitted successfully!')
    form.reset()

    return await response.json()
  } catch (error) {
    // Error handling is automatically done by the form handler
    console.error('Submission failed')
    throw error
  }
}
</script>

Using with Options API

<template>
  <!-- Form template similar to above -->
</template>

<script>
export default {
  data() {
    return {
      // The form will be available as this.form
      form: this.$form({
        name: '',
        email: ''
      })
    }
  },
  methods: {
    async handleSubmit(data) {
      // Submission logic similar to above
    }
  }
}
</script>

API Reference

useForm(initialData)

Creates a form instance with the provided initial data.

Parameters:

• initialData: An object containing the initial form values

Returns: A form instance with the following properties and methods:

| Property/Method | Type | Description | |-----------------|------|-------------| | processing | boolean | Indicates if the form is currently being processed | | progress | number \| null | Upload progress (0-100) or null if not applicable | | errors | object | Object containing validation errors by field name | | isDirty | boolean | Indicates if the form has been modified from its initial state | | hasErrors | boolean | Indicates if the form has any validation errors | | reset() | function | Resets the form to its initial state | | clearErrors() | function | Clears all validation errors | | setError(field, message) | function | Sets a validation error for a specific field | | submit(callback) | function | Submits the form using the provided callback function | | getFields() | function | Returns a plain object with all form fields |

Error Handling

The form handler automatically handles errors from API responses in the following format:

{
  "errors": {
    "email": ["Email is invalid", "Email is already taken"],
    "password": ["Password must be at least 8 characters"]
  }
}

TypeScript Support

The form handler is fully typed and provides type inference for your form data:

interface UserForm {
  name: string;
  email: string;
  age: number;
}

const form = useForm<UserForm>({
  name: '',
  email: '',
  age: 0
})

// form.name will be typed as string
// form.age will be typed as number

License

MIT