useFormState

A powerful form state management composable for Vue/Nuxt applications with Zod validation support.

Features

• ✅ Type-Safe Forms with Zod
• ✅ Reactive Form Data
• ✅ Dirty state tracking
• ✅ Two-Step Confirmations
• ✅ Easy-to-understand Form API (submit, reset, cancel, fill, state, status)

Operations

• Type-Safe Forms with Zod: Define your form's structure using a Zod schema. This automatically types your form data, validation, and submission. It allows partial data during editing but enforces strict validation when you submit.

• Reactive Form Data: The composable provides a reactive state object that you can directly bind to your form inputs using v-model. It works seamlessly with Vue 3 and Nuxt 3.

• Dirty state tracking:

  • status.isDirty: Tells you if any form data has changed from its initial state.
  • status.isFieldDirty('fieldName'): Checks if a specific field has been modified.
  • It intelligently handles "empty" values (like null, '', [], {}) to prevent false "dirty" flags.

• Two-Step Confirmations: reset() and cancel() methods use a two-step process:

  • The first call sets a flag (isResetting or isCancelling) to signal the UI to ask for confirmation.
  • The second call confirms and executes the action. This helps prevent accidental data loss.

• Easy State Updates with fill():

  • fill(data) merges new data into your form's current state.
  • fill(data, { commitAsInitial: true }) updates the form and sets the new data as the initial state, clearing the "dirty" flag.

• Robust Submission Process:

  • submit(callback) strictly validates your form data against the full Zod schema.
  • The status.isSubmitting flag is automatically managed.
  • On successful submission, the form's current data becomes the new initial state, and isDirty is reset.

• Smart Initial State Handling: The composable intelligently builds the form's starting state by combining Zod schema defaults with any initial data you provide.

• Lightweight and Flexible:

  • It uses only Vue's reactivity system and Zod.
  • It has a small, easy-to-understand API (submit, reset, cancel, fill, state, status).
  • It doesn't dictate your UI, so you can use it with any component library or custom inputs.

What This Solves

• Prevents Annoying Validation Errors: You can edit your form without constant validation errors popping up for incomplete fields.
• Reliable Change Detection: Easily know if your form or specific fields have been modified.
• Safe User Actions: Standardizes confirmation steps for actions like resetting or canceling, reducing mistakes.
• Guaranteed Valid Data: Ensures that only data that fully matches your Zod schema is submitted.

When to Use It

• When building forms that need clear validation rules (using Zod).
• For UIs that require robust change detection and confirmation prompts.
• If you prefer a clean, framework-agnostic way to manage form logic.

Important Notes

• Data Cloning and Comparison: The composable uses JSON for cloning and comparing data. This works well for simple data (strings, numbers, arrays, plain objects) but has limitations for complex types like Date objects, functions, or circular references. You might need custom solutions for these.
• fill() for Nested Data: fill() performs a shallow merge. For deeply nested data, you'll need to provide the full nested object or customize the fill function for deep merging.
• Non-Object Schemas: If your Zod schema isn't a ZodObject (e.g., a union), the partial() method might not be available, affecting how initial defaults are handled.

Setup

• 👉 For Nuxt apps, follow the instructions in docs/nuxt.md
• 👉 For Vue apps, follow the instructions in docs/vue.md

License

This project is licensed under the MIT License.