Future Export: useFormData and isDirty

[edmundhung]

Today we are introducing two new experimental APIs under the future export: useFormData and isDirty. These APIs provide a more flexible way to respond to form state changes, with minimal coupling to the form itself.

import { useFormData, isDirty } from '@conform-to/react/future';

These additions let you extend the form in your own direction—without relying on built-in state. Just observe what you care about, and compute only when needed.

useFormData

This is a low-level React hook that lets you derive a value from the current FormData of a form, and re-renders your component only when that value changes.

It works by listening to native form events (input, focusout, submit, reset) and DOM mutations—so it stays in sync even when fields are dynamically added, removed, or renamed.

You can use this to:

• Render live previews or computed summaries

  const fullName = useFormData(formRef, (formData) => {
    const firstName = formData?.get('firstName') ?? '';
    const lastName = formData?.get('lastName') ?? '';
  
    return `${firstName} ${lastName}`.trim();
  });

• Toggle sections of the UI based on field values

  const isShippingAddressMatches = useFormData(
    formRef,
    (formData) => formData?.get('isShippingAddressMatches') === 'on',
  );
  
  return !isShippingAddressMatches ? (
    <Address name={fields.shippingAdress} />
  ) : null;

• Track form state from anywhere, even outside the form

  const dirty = useFormData(
    'example',
    (formData) => isDirty(formData, { defaultValue }) ?? true,
  );
  
  return (
    <button type="submit" disabled={!dirty}>
      Submit
    </button>
  );

  You can pass either a ref to a form-associated element (like a <button>) or a form ID string. This works even if the element is rendered outside the form, as long as it is associated using the form attribute.

Read the full API Reference

isDirty

This is a utility function that compares the current form values with the default values and tells you whether anything has changed.

You can use it to:

• Track the dirty state of a form in combination with useFormData

  const dirty = useFormData(
    formRef,
    (formData) => isDirty(formData, { defaultValue }) ?? false,
  );
  
  return (
    <button type="submit" disabled={!dirty}>
      Save changes
    </button>
  );

• Submit the form only if the form is dirty

  const [form, fields] = useForm({
    defaultValue,
    onSubmit: (event, submission) => {
      if (!isDirty(submission.payload, { defaultValue })) {
        // Prevent submission if there are no changes
        event.preventDefault();
      }
  
      // Handle submission
    },
  });

• Process form submission on the server only if the form is dirty

  export async function action({ request }) {
    const formData = await request.formData();
    const submission = parse(formData, {
      // ...
    });
  
    if (submission.status !== 'success') {
      // Handle validation errors as usual
      return submission.reply();
    }
  
    if (isDirty(submission.payload, { defaultValue })) {
      // Process the submission / save changes only if the form is dirty
    }
  
    return redirect('/success');
  }

The function compares the full FormData object against the defaultValue you provide. This is not always the same as the initial values of the form, especially if the form includes hidden fields used for server-side processing or security purpose, such as CSRF tokens.

To avoid false positives in these cases, you can use the skipEntry option to ignore specific fields during comparison:

isDirty(formData, {
  defaultValue,
  skipEntry: (name) => name === 'csrf-token',
});

Read the full API Reference

Why these APIs?

While similar functionality is available today through useForm, these new primitives are designed to decouple form state from core logic, giving you more control over how and when to derive what you need.

They also lay the foundation for upcoming changes to useForm, which will adopt a simpler state model and reduce built-in subscriptions. Going forward, APIs like useFormData and isDirty will allow you to reintroduce those behaviors only where you need them, without the overhead of tracking everything by default.

These APIs are still experimental and may evolve before being promoted to stable. If you try them out, we would love to hear your feedback. Let us know what you build!

[oxc]

Do you think it would be possible to make the values of single static fields more easily accessible? It seems weird to have to parse the FormData myself if I have already set up the schema in the useForm call.

Especially for multi value fields, and for nested objects/arrays, it seems very cumbersome and error prone to work on the FormData manually.

[edmundhung]

Just see your additional example, yep. No problem at all. I can provide that

[oxc]

That would work. I thought you want to access the value of a nested list directly which I have no way to make sure it matches the type. So something like this?

const { value, options, checked } = getInputValue(formData, name);

• value being a string with the first entry value in the formData
• options being a array with all matching entries in the formData
• checked being a boolean derived from value === 'on'

Exactly. Does that sound useful?

[edmundhung]

But... now I wonder if you really need an API:

Your example (options) can be written as:

const isAdditionalServicesSelected = useFormData(formRef, (formData) => {
    return formData?.getAll(fields.services.name).includes("additional-services") ?? false;
});

If you need a value, then it would be:

const value = useFormData(formRef, (formData) => {
    return formData?.get(fields.services.name) ?? '';
});

If you need a checked state, it will be:

const checked = useFormData(formRef, (formData) => {
    return formData?.get(fields.services.name) === 'on';
});

[oxc]

Ah, I did not know about getAll. That indeed changes things 😄

[oxc]

And when I started writing that question, I still had literal names instead of using field.name.

With those two changes I think it's fine. Thanks 😄

[andrew-shpak]

Is it possible to use hidden field as formRef for useFormData along with useControl ? For instance

const control = useControl({
    defaultValue: field.defaultValue,
  });
 <input
        type="hidden"
        name={name}
        ref={control.register}
      />
     const checked = useFormData(control.register, (formData) => {
     return formData?.get(fields.services.name) === 'on';
});

[edmundhung]

Yes. The hook will resolve the associated form element automatically as long as they are associated in the DOM, meaning your input either render inside a <form /> element or using the form attribute (e.g. <input form="my-form-id">)

Also mentioned in the tips here: https://conform.guide/api/react/future/useFormData#tips

[edmundhung]

Sorry, I misread your question 🤦🏼

This is not possible at the moment. You will need to setup additional ref manually:

const inputRef = useRef();
const control = useControl({
    defaultValue: field.defaultValue,
});

<input
  type="hidden"
  name={name}
  ref={element => {
     control.register(element);
     inputRef.current = element;
  }}
/>
const checked = useFormData(inputRef, (formData) => {
  return formData?.get(fields.services.name) === 'on';
});

But I agree we should make this easier. Perhaps something like this?

const checked = useFormData(control.ref, (formData) => {
  return formData?.get(fields.services.name) === 'on';
});

[andrew-shpak]

Would be nice to have such feature, because inputRef and control.register are identical