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

[edmundhung]

Added control.formRef in v1.13.0.

[jansedlon]

Does this hook useFormData supports subscribing to more complex data structures like array of objects? Subscribing to that using FormData is rather cumbersome.

Let's say that I'm building a realtime editor of sales pages. I want the user to create custom fields. Each field is of type

{
  type: "checkbox" | "input" | "radio";
  options: string[];
  defaultValue: string;
}

And with each option the user adds (using intents) I want to display that somewhere else. I'd like to not have to sync this with external state manager but rather simply subscribe to that value somewhere else (still inside FormProvider though).

As of now I'm using

const [field] = useField('name');

// field.value

[jansedlon]

This is why option 1 returns any instead to keep it easy to work with as long as you know what the field is, without lying on the types.

This is true but that's a devil's tool 😅 Because then if you change the schema, you don't get an error the same way it would have been unknown because someone forgot the change the name in the form as well.

const value = useFormData(form.id, formData => {
 const field = getFieldValue(formData, 'name');
 const result = fieldSchema.safeParse(field);
 
 return result.success ? result.data : null;
});

This makes sense but honestly I cannot imagine parsing and subscribing together, it could very well become an overhead without some kind of memoization (e.g. subscribing on every keystroke in certain scenarios for array of objects which are more than 1 level deep)

[edmundhung]

This is true but that's a devil's tool 😅

Haha, true. This is why I wonder if option 2 is a good compromise here. Maybe a type option to opt-in to different behavior?

const name = useFormData(form.id, formData => getFieldValue(formData, 'name'));
//    ^? unknown
const address = useFormData(form.id, formData => getFieldValue(formData, 'address', { type: 'object' }));
//    ^? Record<string, unknown> | undefined
const array = useFormData(form.id, formData => getFieldValue(formData, 'array', { type: 'array' }));
//    ^? Array<unknown> | undefined
const task = useFormData(form.id, formData => getFieldValue<{ content: string }>(formData, 'task', { type: 'faith' }));
//    ^? { content?: string } | undefined

I know type: 'faith' sounds a bit ridiculous. But I do prefer correctness by default. Making it opt-in would make sure it is explicit to users in terms of the the consequence.

it could very well become an overhead without some kind of memoization

I could introduce additional option to useFormData to restrict when the selector runs by providing a scope (e.g. a parent name so that only changes on child fields will trigger the selector to rerun). But I am not too worry about the overhead as most of the schema library are fairly performant.

[jansedlon]

But I do prefer correctness by default. Making it opt-in would make sure it is explicit to users in terms of the the consequence.

I agree.

If you don't want this to be a runtime config, you can do the same Remix team did with the introduction of singleFetch. If you wanted to enable it, you created a dts file and specified an interface there.

And the in the types they decided by the interface

https://github.com/remix-run/remix/blob/f70cb5c14536f1e92b2cc6c125a9f706e5034ca5/packages/remix-server-runtime/serialize.ts#L30

This would be cool to also be able to define this globally.

[edmundhung]

@jansedlon How about this?

[edmundhung]

The getFieldValue API is already landed in v1.15.0.

[tyforcode]

Is there anyway to have getFieldValue play nicer with useFormData? Since useFormData returns a value in the select of URLSearchParams | FormData | null and getFieldValue only accepts non-null URLSearchParams | FormData, there will always be a type error unless there's a null check around each implementation.

[oxc]

I just stumbled across that myself. I guess it will be much nicer soon, when #1142 is released.

[tyforcode]

For sure. Thanks!

[edmundhung]

Fixed in v1.16.0. The useFormData() selector is called only when the formData is available now.