Add dirtyFields to useForm for Per-Field Dirty Tracking

[kevindees]

Problem

The useForm helper’s isDirty property shows if any field has changed, but there’s no built-in way to check which fields are dirty without extra code. This is a frequent need for form UIs (e.g., marking changed fields).

Solution

Add a dirtyFields property to useForm, a reactive object that tracks which fields have changed. Example:

const form = useForm({ name: 'John', email: '[email protected]' });
form.name = 'Jana';
console.log(form.dirtyFields); // { name: true, email: false }
console.log(form.isDirty); // true

This builds on the existing initial-value tracking in useForm, exposing per-field states reactively (e.g., via computed in Vue). It’s inspired by React Hook Form’s dirtyFields https://react-hook-form.com/docs/useformstate and relates to prior discussions in PR #1387, where form state enhancements were explored.

Implementation

Current Implementation (Vue)

watch(
    form,
    (newValue) => {
      form.isDirty = !isEqual(form.data(), defaults)
      if (rememberKey) {
        router.remember(cloneDeep(newValue.__remember()), rememberKey)
      }
    },
    { immediate: true, deep: true },
  )

New Implementation (Vue)

This is just to demo the idea via a quick example; it does not implement deep field checking like getDirtyFields.test.ts. Starting small and allowing checks at the root level only at first seems like an expandable approach. If deep checks were introduced later, it would not cause backward compatibility issues. [example deep check here]

watch(
  form,
  (newValue) => {
    const currentData = form.data()
    form.isDirty = !isEqual(currentData, defaults)
    // Update dirtyFields
    Object.keys(defaults).forEach((key) => {
      form.dirtyFields[key] = !isEqual(currentData[key], defaults[key])
    })
    // Clean up dirtyFields for removed keys
    Object.keys(form.dirtyFields).forEach((key) => {
      if (!(key in defaults)) delete form.dirtyFields[key]
    })
    if (rememberKey) {
      router.remember(cloneDeep(newValue.__remember()), rememberKey)
    }
  },
  { immediate: true, deep: true },
)

Like isDirty (for onSuccess(), const form = reactive({}), and other place), we can set the default to an empty object {} to standardize the clean value regardless of the form data set. So, when this.isDirty = false to reset it, we set this.dirtyFields = {}.

this.isDirty = false;
this.dirtyFields = {};

Finally, we might need to follow the pattern of errors when a restore or remember happens. I'm not sure if we should ignore them or not.

__remember() {
  return { data: this.data(), errors: this.errors, dirtyFields: this.dirtyFields }
},
__restore(restored) {
  Object.assign(this, restored.data)
  this.setError(restored.errors)
  this.setDirtyFields(restored.dirtyFields)
},

Why?

1. Saves devs from writing custom dirty checks.
2. Keeps isDirty unchanged while adding granularity.
3. Ties into community interest in useForm (see Adds clearChangedErrors method to clear changed fields errors #1387, Make isDirty reactive to defaults #2236).