Future Export: the useForm hook

[edmundhung]

We are super excited to announce the future useForm hook today! This brings first-class support for React 19 Server Actions, a refined validation setup, and more.

import { useForm } from '@conform-to/react/future';

The motivation

When we first built Conform v1, we had a simple goal: make form state as accessible as possible to developers. We wanted you to just write fields.email.value and have everything work magically.

So we synced all form values into React state and built complex subscription patterns to avoid re-renders. It worked beautifully—until we realized we had created something that was incredibly hard to debug and reason about.

Over the last year, we have been thinking about how to simplify this, and then came the lightbulb moment: Conform already uses the DOM as the source of truth. Why are we duplicating all this state in React? What if we just... didn't?

The new useForm hook is the result of that realization. No form values in React state. The rest of the state like errors or touched fields doesn't change that often, so we can model it with a simple useState. This makes the architecture much simpler and easier to maintain.

What's different

This release has addressed a lot of the outstanding issues with new features and improvements. Here are some of the highlights:

Metadata

The most obvious change is that the new hook returns a structured object instead of an array tuple, with some metadata changes:

• Form props can be accessed through form.props directly instead of using getFormProps(form)
• Form actions like form.validate() and form.reset() are now available on the intent object instead
• Form dirty state (form.dirty) is removed. Use useFormData() with the isDirty helper if you need this.
• Form metadata now offers three methods for dynamic field metadata access: getField(name), getFieldset(name) and getFieldList(name).
• Field values (e.g. fields.email.value) are removed. Use useFormData() to read form values when needed.
• Field initial values (e.g. fields.email.initialValue) are removed. Use fields.email.defaultValue / fields.email.defaultOptions / fields.email.defaultChecked instead.

const { form, fields, intent } = useForm({
  // ...
});

return (
  <form {...form.props}>
    <input
      type="email"
      name={fields.email.name}
      defaultValue={fields.email.defaultValue}
    />
    {fields.email.errors}
    <input
      type="password"
      name={fields.password.name}
      defaultValue={fields.password.defaultValue}
    />
    {fields.password.errors}
    <button>Login</button>
  </form>
);

We have also adjusted the return type of useField(), which returns a single field's metadata instead of an array tuple with both form and field metadata:

import { useField } from '@conform-to/react/future';

function FormField({ name }) {
  const field = useField(name, { formId: 'optional-form-id' });

  // ...
}

The arguments of useFormMetadata() have also changed to accept an object with optional formId instead of a formId string directly.

import { useFormMetadata } from '@conform-to/react/future';

function FormSummary() {
  const form = useFormMetadata({ formId: 'optional-form-id' });

  // ...
}

Validation

Another big change is the validation system. The onValidate callback now receives the parsed payload alongside the FormData and requires you to return a structured error:

import { type FormError, useForm } from '@conform-to/react/future';

const { form, fields, intent } = useForm({
  onValidate({ payload }) {
    const error: FormError = { formErrors: [], fieldErrors: {} };

    if (!payload.email) {
      error.fieldErrors.email = ['Email is required'];
    }

    if (!payload.password) {
      error.fieldErrors.password = ['Password is required'];
    }

    return error;
  },
});

Of course, we have helpers to integrate with popular schema libraries like Zod:

import { useForm } from '@conform-to/react/future';
import { coerceFormValue, formatResult } from '@conform-to/zod/v3/future'; // or "@conform-to/zod/v4/future"
import { z } from 'zod';

// Enhance your schema to coerce form values
const schema = coerceFormValue(
  z.object({
    email: z.string().email(),
    password: z.string(),
  }),
);

function Example() {
  const { form, fields, intent } = useForm({
    onValidate({ payload }) {
      // Parse the payload with zod yourself
      const result = schema.safeParse(payload);
      // Transform zod result into FormError
      return formatResult(result);
    },
  });

  // ...
}

But we have something even better: standard schema support. Simply pass your schema to useForm and it will handle parsing and validation for you:

const { form, fields } = useForm({
  schema,
});

On the server side, you will find a new parseSubmission utility that parses FormData into a structured submission object with a clean payload for easy validation. Use the report helper to send results back to the client:

import { parseSubmission, report } from '@conform-to/react/future';
import { coerceFormValue, formatResult } from '@conform-to/zod/v3/future';
import { z } from 'zod';

const schema = coerceFormValue(
  z.object({
    email: z.string().email(),
    password: z.string(),
  }),
);

export function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  const submission = parseSubmission(formData);
  // Validate the payload with zod yourself
  const result = schema.safeParse(submission.payload);

  if (!result.success) {
    return {
      // Create a submission result using the `report` helper
      result: report(submission, {
        error: formatResult(result),
      }),
    };
  }

  // ...
}

We have also improved client async validation support. You can now define async validation directly in your schema and pass it to useForm:

const schema = coerceFormValue(
  z.object({
    username: z
      .string({ required_error: 'Username is required' })
      .refine((username) => isUsernameUnique(username), {
        message: 'Username is already used',
      }),
  }),
);

const { form, fields } = useForm({
  schema,
});

However, validation might trigger regardless of which field the user is typing in, so we recommend using a memoize utility to cache async validation results:

import { memoize } from '@conform-to/zod/future';

const schema = useMemo(
  () => {
    // Cache results so that it skips duplicate requests for the same username
    const isUsernameUnique = memoize(async (username: string) => {
      const response = await fetch(`/api/validate?username=${username}`);
      return response.ok;
    });

    return coerceFormValue(
      z.object({
        username: z
          .string({ required_error: 'Username is required' })
          .refine((username) => isUsernameUnique(username), {
            message: 'Username is already used',
          }),
      }),
    ),
  },
  [],
);

You can also validate manually in the onValidate callback if you need more control. See the examples section below for more details.

Progressive enhancement

The new design takes a more targeted approach to progressive enhancement. You still get core support like preserving user input on validation errors, but some advanced features require additional setup:

• parseSubmission doesn't handle intents automatically
• getButtonProps() method is no longer available

We still believe the best way to build resilient web apps is to use the web platform extensively. However, building a form with a complete no-JS experience introduces additional complexity that not every application needs. The new design still supports full progressive enhancement, but it requires additional setup that we will document separately.

Improved intent handling

Previously, calling multiple form actions required wrapping each in flushSync to avoid form state sync issues. The new intent system eliminates this need:

<button
  type="button"
  onClick={() => {
    // Inserting two items will only cause one re-render now
    intent.insert({
      name: 'todos',
      defaultValue: { text: '', completed: false },
    });
    intent.insert({
      name: 'todos',
      defaultValue: { text: '', completed: false },
    });
  }}
>
  Add Two Items
</button>

You can also access the intent object anywhere in your component tree using the useIntent() hook:

import { useIntent } from '@conform-to/react/future';

function RemoveButton({ name, index }: { name: string; index: number }) {
  const buttonRef = useRef<HTMLButtonElement>(null);
  const intent = useIntent(buttonRef);

  return (
    <button
      type="button"
      ref={buttonRef}
      onClick={() => intent.remove({ name, index })}
      form="optional-form-id"
    >
      Remove
    </button>
  );
}

Additional improvements

Custom error handling: By default, Conform focuses the first invalid field when validation fails. You can now customize this behavior with the new onError option:

const { form, fields } = useForm({
  onError({ error, formElement }) {
    if (error.formErrors) {
      toast.error(error.formErrors.join('\n'));
    }
  },
});

React 19 compatibility: Previously, Conform required a special workaround to disable React 19's automatic form reset behavior. We have adjusted the state model so it now works seamlessly with Server Actions.

Examples

We have updated several examples to showcase the new useForm hook, including a new React SPA example:

• React SPA Example
• React Router Example
• Next.js Example

Try it out and share your feedback! The API is stabilizing, but we are still open to suggestions before the official v2 release.

[afoures]

does this new useForm works with native html reset via <button type="reset" />?

[edmundhung]

Good question! I initially dropped support for the reset button to better align with React 19. In React 19, a reset event is dispatched automatically after a server action, regardless of whether the submission succeeds or fails. That can be problematic, since you might not want the form state to reset when the submission fails.

Another part of the issue is that Conform listens to the native reset event directly, while React intentionally hides it by not calling your onReset handler.

So right now, it doesn't support it. But it could. Should it? 🤔

[edmundhung]

I think supporting reset button is effectively doing this for you:

function Example() {
  const { form, fields, intent } = useForm({
    // ...
  });

  return (
    <form {...form.props} onReset={() => intent.reset()}>
      {/* ... */}
      <button type="reset">Reset</button>
    </form>
  );
}

[edmundhung]

Just give it a second thought and I think there might be issue with the approach above as intent.reset() will dispatch a reset event as well. So we need additional logic to stop it from triggering recursively.

[edmundhung]

I tested this and, surprisingly, the solution above works fine. However, it does run into an infinite loop if you call formElement.reset() manually.

I will make both works with the future useForm hook.

[aaronschwartz]

I see that getFormProps() has been moved to form.props. What is the plan for getInputProps? Will it be rewritten for V2, moved to a field prop, or something else? Also I see that there is no longer a form.errorId prop. I know you're just getting started with V2, I was just wondering what the future holds. I'm starting some new development and would like to start using V2 instead of having to do a huge migration later.

[aaronschwartz]

Thanks for the reply. It was helpful to set all of the aria attributes correctly, but if I know it's not going to be there then I'll just remake a similar function myself. I don't really like the idea of my custom form components being aware of the conform types so I probably wouldn't integrate it directly into my custom components.

[edmundhung]

I don't really like the idea of my custom form components being aware of the conform types so I probably wouldn't integrate it directly into my custom components.

That makes sense. Do your custom inputs expose an interface compatible with native inputs? That has always been my personal preference too, but I do not see it done much in practice, probably because most people prefer rendering the UI library component directly. That is also why I am planning a way to customize metadata.

I am open to rethinking this, either bringing back the props getter, or exposing it as metadata instead (e.g. fields.email.inputProps with the name, validation attributes, and aria attributes).

[edmundhung]

Also I see that there is no longer a form.errorId prop.

This should be fixed in v1.9.1.

[aaronschwartz]

Do your custom inputs expose an interface compatible with native inputs?

That's a good point. I'm currently trying to integrate with the Catalyst library which uses HeadlessUI as the base. It does seem mostly compatible with the native interfaces.

[edmundhung]

I have implemented the custom metadata feature in #1047.

[aaronschwartz]

Whenever I add a file upload input to the page and try to submit the form (to a react-router action), Chrome crashes with a "Error code: RESULT_CODE_KILLED_BAD_MESSAGE". Have you tested with file uploads? I'm not 100% sure what is happening, but if I submit without going through the Conform onSubmit handler then the action works as intended.

[edmundhung]

Does this happen every time for you, or only occasionally? I managed to reproduce it as well, though it seems a bit random on my end. I have some ideas about what might be going wrong and will work on a patch tomorrow. Thanks for reporting it!

[aaronschwartz]

It's 100% if it goes through the Conform onSubmit handler. I also thought it was random at first, but it was because it was working if I submitted quickly before all of the JS loaded so the form was being posted without going through the client side Conform code.

[edmundhung]

Yep, I can reproduce the issue properly now. It looks like the root cause is Conform accidentally updating the file input with the empty default file set by the browser 😓

I will have a patch ready tomorrow.

[edmundhung]

This is fixed in v1.10.0.

[tkoyasak]

Question about form.valid with future API

Hi, thanks for the new future API, I’m trying it out and noticed something I don’t fully understand.

When I use the current API, the form.valid property correctly updates based on validation.
But with the future API, form.valid always seems to remain true, even if the field value is invalid (e.g. greater than 100).

Here’s a minimal example comparing the two:

import { getFormProps, useForm } from '@conform-to/react';
import { useForm as future_useForm } from '@conform-to/react/future';
import { unstable_coerceFormValue as coerceFormValue, parseWithValibot } from '@conform-to/valibot';
import * as v from 'valibot';

const schema = v.object({
  index: v.pipe(v.number(), v.minValue(0), v.maxValue(100)),
});

export function FormWithCurrentAPI() {
  const [form, fields] = useForm({
    shouldValidate: "onInput",
    shouldRevalidate: "onInput",
    onValidate: ({ formData }) => {
      return parseWithValibot(formData, { schema });
    }
  })

  return (
    <form {...getFormProps(form)}>
      <div>Current API</div>
      <div>{form.valid ? "valid" : "invalid"}</div>
      <div>
        <label htmlFor={fields.index.id}>Index</label>
        <input
          id={fields.index.id}
          name={fields.index.name}
          defaultValue={fields.index.defaultValue}
        />
        <div>{fields.index.errors}</div>
      </div>
    </form>
  )
}

export function FormWithFutureAPI() {
  const { form, fields } = future_useForm({
    shouldValidate: "onInput",
    shouldRevalidate: "onInput",
    schema: coerceFormValue(schema),
  });

  return (
    <form {...form.props}>
      <div>Future API</div>
      <div>{form.valid ? "valid" : "invalid"}</div>
      <div>
        <label htmlFor={fields.index.id}>Index</label>
        <input
          id={fields.index.id}
          name={fields.index.name}
          defaultValue={fields.index.defaultValue}
        />
        <div>{fields.index.errors}</div>
      </div>
    </form>
  )
}

Steps to reproduce

• Enter a number greater than 100.
• In the Current API, form.valid becomes false.
• In the Future API, form.valid stays true.

Question

Is this the intended behavior of the future API?
Or am I missing some configuration to make form.valid reflect the validation result?

Thanks a lot!

[edmundhung]

Looks like I misconfigured it to depend on whether there are any form-level errors 😅 I will fix it tonight. Thanks!

[edmundhung]

#1024 should fix the valid metadata issue. Feel free to try the pre-release linked in the comment. I will land it tomorrow.

[tkoyasak]

Just tested the pre-release, and it works correctly. Thanks a lot for the quick fix!

[edmundhung]

This is landed in v1.10.0.

[aaronschwartz]

I notice that server actions feel a little complex in this new version.

It's nice to be able to pass in a standard schema property to the useForm({schema}) property on the client side, but on the server side, it requires a parseSubmission followed by a schema.safeParse followed by a report and then a formatResult all just to make sure the Conform boiler plate is hooked up correctly for everything to work.

It would be nice to have a similar shortcut on the server side such as const result = parseSubmission(formData, schema) with a simple result.conformReply() or something similar.

It's nice to have the granular control over everything, but we lack that same control on the client side. This came up because I was trying to integrate the HeadlessUI 2.0 ComboBox without relying on the useControl hook since the combobox already generates it's own hidden inputs with a custom naming scheme. The problem is that the naming scheme is in the form gym[id], gym[name] which causes Conform to crash when trying to parse the names with Invalid path syntax at position 3 in "gym[id]. On the server side I could make it work by using my own version of a parseSubmission, but there's no similar granularity on the client side that I can find.

[edmundhung]

just to make sure the Conform boilerplate is hooked up correctly for everything to work.

That's fair. The server side is definitely a bit messier to work with right now. From what you wrote, it sounds like you are looking for an experience closer to parseWithZod in v1?

integrate the HeadlessUI 2.0 ComboBox without relying on the useControl hook since the combobox already generates its own hidden inputs with a custom naming scheme.

I have not had a chance to dig into HeadlessUI 2.0 yet. That said, I have not run into a case where you must rely on the inputs generated by UI libraries, aside from progressive enhancement. Since you mentioned multi-inputs, I do not think that applies in your case either. With generated inputs, you lose control over how values are serialized (and, as you noted, the naming too).

I can certainly consider exposing a hook to customize how submissions are parsed from FormData, but at least from my perspective this does not seem like a strong reason to depend on the library-generated inputs.

[edmundhung]

Hopes this makes it simpler on the server: #1041

[oxc]

The new future exports sound great, seems like some corners have been straightened out (or removed) 👍🏻

Do I understand correctly though, that the only way to infer the FormShape is by passing a standard-schema schema prop? Inferring via onValidate is no longer supported.

So if I do not want to rely on schema for some reason, I have to pass the FormShape type parameter manually, correct?

(Click here for Context)

I'm still not happy with Zod's i18n support, even though it has improved with v4. Therefore, I need to pass my own i18n errormap to the parse function, which is not possible via Zod's standard-schema implementation. So I have to either wrap that, or do the parsing in onValidate and pass the inferred type myself. Or find another way to get happy with Zod i18n :)

[edmundhung]

@oxc I would love to know your thoughts on this: #1069

[oxc]

On first glance, this looks really promising. I'll give it a more in-depth review tomorrow, hope that's sufficient for you.

[oxc]

Nice, I love it. Feels good to have the standard-schema validation out of the onValidate implementation.

I'm still wondering what it would take to allow a custom schema implementation to be passed without having to override global types. Some kind of adapter. But in the end, that adapter could simply be a StandardSchema adapter for that schema, so that already works.

A bit off-topic, but can you quickly explain why the »"onValidate" handler is not supported when used with asynchronous schema validation«?

[oxc]

Also, that CustomSchema implementation is really clever 🦊

[edmundhung]

I have thought about exporting a validateSchema helper from the zod package with CustomSchema automatically extended for you. But two concerns:

• @conform-to/zod does not depends on @conform-to/react. Not really a user problem but it means we are coupling two packages.
• I am not sure how useful it would be with a default validateSchema implementation. It might not fit everyone's need and it's fairly straight forward to customize yourself.

Not against this idea but I would wait until more people ask for it.

can you quickly explain why the »"onValidate" handler is not supported when used with asynchronous schema validation«?

We can support it but it wasn't clear to me why people would want to do it. There are 4 cases here:

• Sync schema validation > Sync onValidate > UI updated
• Sync schema validation > Async onValidate (> Optionally, Update UI first) > Update UI again when resolve
• Async schema validation > Wait until resolve > Sync onValidate > UI updated
• Async schema validation > Wait until resolve > Async onValidate > (> Optionally, Update UI first) > Update UI again when resolve

I can think of good usecases for the first 2 scenario, but the later 2 feels strange. I guess I fail it just so people can tell me why they want it 😅

[tkoyasak]

Hi, I saw PR #1041 , which adds support for passing schema issues directly to report. That looks really useful!

Do you think the same improvement could also apply to the onValidate callback in useForm?
Right now, we still need to use formatResult, but if onValidate could return issues directly, the code would become simpler and more consistent with report.

// current
onValidate: ({ payload }) => {
  const result = schema.safeParse(payload);
  const { value, error } = formatResult(result, { includeValue: true });
  if (value) setState(value);
  return error;
},

// proposed
onValidate: ({ payload }) => {
  const result = schema.safeParse(payload);
  if (result.success) {
    setState(result.data);
    return null;
  }
  return { issues: result.error.issues };
},

This would:

• align the API between report and onValidate
• reduce boilerplate when working with Zod/Valibot
• still allow formatResult for customization when needed

Would you consider extending the same support to onValidate?

[tkoyasak]

Sorry, my earlier explanation wasn’t very clear. Let me rephrase with a more concrete example.

Right now, if I want to use the actual input values, I end up either:

import * as v from 'valibot';

const dateField = v.pipe(
  v.string(),
  v.regex(/^\d{4}(?:-(?:0[1-9]|1[0-2]))?$/, "YYYY or YYYY-MM."),
);

const schema = v.pipe(
  v.partial(
    v.object({
      title: v.string(),
      creator: v.string(),
      publisher: v.string(),
      mediatype: v.array(v.string()),
      from: dateField,
      until: dateField,
    }),
  ),
  v.forward(
    v.check(
      ({ from, until }) => !from?.length || !until?.length || from.length === until.length,
      "`from` and `until` should have the same format.",
    ),
    ["until"],
  ),
  v.transform((input) => 
    Object.entries(input)
      .filter(([_, v]) => v !== undefined)
      .map(([k, v]) => [k, Array.isArray(v) ? v.join(" ") : v.toString()]),
  ),
  v.nonEmpty(),
);

const transformToUrl = v.pipe(
  schema,
  v.transform((input) => `${API_URL}?${new URLSearchParams(input).toString()}`),
);

1. storing the parsed value in an external state inside onValidate (using safeParse myself), like this:

const [data, setData] = useState(null);

const { form } = useForm({
  onValidate: ({ payload }) => {
    const result = transformToUrl.safeParse(payload);
    if (result.success) {
      setData(result.data);
      return null;
    }
    return formatResult(result);
  },
});

return <div>{form.valid ? data : "inputs are invalid"}</div>;

2. subscribing to useFormData and re-parsing the FormData object manually, like this:

const { form } = useForm({ schema });

const data = useFormData(formRef, (formData) => {
  if (!formData) return null;

  const input = parseSubmission(formData);
  return `${API_URL}?${new URLSearchParams(
    Object.entries(input)
      .filter(([_, v]) => v !== undefined)
      .map(([k, v]) => [k, Array.isArray(v) ? v.join(" ") : v.toString()])
  ).toString()}`
});

return <div>{form.valid ? data : "inputs are invalid"}</div>;

Both approaches work, but in the second one, even though the schema is already applied for validation, I still have to re-parse the form data when I want to consume it.

That’s why I feel it’s often easier to just define a transform in the schema (e.g. zod/valibot) and reuse the result, instead of parsing form data again outside.

[edmundhung]

It seems to me you are just looking for a way to serialize the form data as a search string based on the current formData, what about this?

const { form } = useForm({ schema });
const data = useFormData(form.id, (formData) => {
    if (!formData) return null;

    const searchParams = new URLSearchParams();

    for (const name of formData.keys()) {
        searchParams.set(name, formData.getAll(name).join(' '));
    }

    return `${API_URL}?${searchParams.toString()}`;
});

return <div>{form.valid ? data : "inputs are invalid"}</div>;

For your particular case, I don't think you really need the value. 🤔

[edmundhung]

I think I will go ahead with my suggestion on #1014 (reply in thread). I do plan to add custom form state support soon. But there are other things I want to prioritize first.

[tkoyasak]

Thanks for the example. I see that in my case, generating the search string directly from formData would work.

Your suggestion to pass schemaResult also looks like a very helpful improvement. Since my schema is synchronous, the async limitation you mentioned wouldn’t be an issue for me.

Thanks again for considering this!

[edmundhung]

This is landed in v1.11.0.

[oxc]

I find myself tripping over the missing DefaultMetadata export often when trying to write some abstractions for my forms. For example, I want to write a Field component that takes a FieldMeta with ErrorShape restricted to string, which seems impossible without re-defining DefaultMetadata myself.
Does anything speak against exporting the DefaultMetadata type?

[oxc]

Sorry, I missed that response in the other thread.

[edmundhung]

No worries. I think #1045 should address your issue. I don't expect making any breaking changes on it anymore. If I will change it again, it would just be additional generic with a default type. So it should be safe to use.

[oxc]

Had a quick look, sounds good ❤️

[edmundhung]

This is landed in v1.11.0.

[edmundhung]

I have implemented the custom metadata feature in #1047.

[oxc]

How does that work with asynchronous schema validation on the client side?

I played around with standard schema yesterday, and noticed that some fields would not should validation errors when I submitted the form empty. When I switched from safeParseAsync to safeParse, it worked again.

Does async validation require some kind of suspense around the form elements?

[oxc]

Here are the differences in form.context (scroll down for diff), maybe that already gives you a hint. I'll try to create a minimal example later this week.

https://gist.github.com/oxc/eb7bbae8acd5639274b2c62338b4f588

In case you're wondering: neither the async nor the sync page make any kind of requests after the first render. These serverError/serverIntendedValue in the async case are generated client-side.

[edmundhung]

Thanks, that's probably enough. I can see the issue you had with the services field. Its errors are missing on async validation as it is not considered touched.

Conform does some additional logic on client (sync) validation to mark non existent fields as touched when doing a normal form submit, but that logic is skipped on server (async) validation. So that's likely the reason why this happens.

I will look into a solution tonight.

[oxc]

Thanks. The services are a list of checkboxes, so indeed no value would be present for those.

[edmundhung]

#1048 should fix your issue. Can you give the pre-release a try?

[oxc]

Yep, looks good 👍🏻

The field now shows up in touchedFields

I've updated the gist with the new values, here you can see the diff: https://gist.github.com/oxc/eb7bbae8acd5639274b2c62338b4f588/revisions

Thanks!

[andrew-shpak]

I am trying to add new value by using intent from useForm, but my ide show me type error - Type string is not assignable to type Partial<any>. Is this issue on ide/code side ?

 intent.insert({
                          name: name,
                          index: index + 1,
                          defaultValue: "",
                        });
                        

[andrew-shpak]

Sure. So I have filter form and I store state of selected filter values inside url. Then I click reset intent reset is called and back to default values. This is correct in case when default values are undefined or null, but if like in may case default values is pre defined values so intent reset does not work. For instance:
Default values:
{ name: “” } - works
{ name: “test”} - intent reset not works

[edmundhung]

Just to clarify: are you looking for a way to clear all fields, or do you really want to reset the whole form?

I have been thinking recently when people should use reset, and it feels like a lot of the time resetting the whole form state might not be the best choice 🤔

[andrew-shpak]

Well, actually I need full form reset.
Also I tries 1.12.1 and typing works and would be nice when Zod(in may case) form types like number or string checked by intent
apart of it by next message I have provide full example of current usage of reset and in case of 10-20 fields( have such filters form) not the best DX

[edmundhung]

That's fair. You will be able to clear all fields while resetting the state with the new defaultValue option introduced in #1065:

intent.reset({ defaultValue: null })

Can you give the pre-release listed in the PR comment a try?

[edmundhung]

This is landed in v1.13.0. Thanks for all the feedback over the last week. They are super helpful!

[andrew-shpak]

Conform v1 allow to set reset({}) but with v2 I need to have

intent.update({
                name: fields.name.name,
                value: "",
              });
              intent.update({
                name: age,
                value: "",
              });
              intent.update({
                name: fields.year.name,
                value: "",
              });
              intent.update({
                name: fields.field.name,
                value: "",
              });

when default values are initially populated

[edmundhung]

What types do you see with fields.approved.name?

Looks like useForm might have failed to infer the form shape from you schema. How is your useForm hook setup look like?

[andrew-shpak]

What types do you see with fields.approved.name?

Looks like useForm might have failed to infer the form shape from you schema. How is your useForm hook setup look like?

Well, initially IDE does not autocomplete any fields what exist in form.

import { FormProvider, useForm } from "@conform-to/react/future";
import { getZodConstraint } from "@conform-to/zod/v4";
import { formatResult } from "@conform-to/zod/v4/future";
-------
const [searchParams, setSearchParams] = useSearchParams();
  const searchParamsEntries = Object.fromEntries(searchParams);
const { form, fields, intent } = useForm({
    defaultValue: searchParamsEntries,
    constraint: getZodConstraint(coursesFilterSchema),
    onValidate({ payload }) {
      const result = coursesFilterSchema.safeParse(payload);
      return formatResult(result);
    },
  });
--------- 
import { z } from "zod";
import { coerceFormValue } from "@conform-to/zod/v4/future";

const coursesFilterSchema = coerceFormValue(
  z.object({
    scientificSpecialtyId: z.string().optional(),
    approved: z.string().optional(),
    selective: z.string().optional(),
  })
);
export type CoursesFilter = z.infer<typeof coursesFilterSchema>;
export { coursesFilterSchema };
-----------------------
fields.approved.name /// name: FieldName<any>

[edmundhung]

That's because useForm can only infer the schema type when you use the schema option.

Is there any reason why you can't do this?

const { form, fields, intent } = useForm({
    defaultValue: searchParamsEntries,
    constraint: getZodConstraint(coursesFilterSchema),
    schema: coursesFilterSchema,
});

The only case I know this won't work is when you want to pass schema specific options, e.g. an error map to the zod schema and is definitely something I need to solve before v2.

A temporary solution would be typing it manually:

const { form, fields, intent } = useForm<z.infer<typeof coursesFilterSchema>>({
    defaultValue: searchParamsEntries,
    constraint: getZodConstraint(coursesFilterSchema),
    onValidate({ payload }) {
      const result = coursesFilterSchema.safeParse(payload);
      return formatResult(result);
    },
});

[andrew-shpak]

That's because useForm can only infer the schema type when you use the schema option.

Is there any reason why you can't do this?

const { form, fields, intent } = useForm({
    defaultValue: searchParamsEntries,
    constraint: getZodConstraint(coursesFilterSchema),
    schema: coursesFilterSchema,
});

The only case I know this won't work is when you want to pass schema specific options, e.g. an error map to the zod schema and is definitely something I need to solve before v2.

A temporary solution would be typing it manually:

const { form, fields, intent } = useForm<z.infer<typeof coursesFilterSchema>>({
    defaultValue: searchParamsEntries,
    constraint: getZodConstraint(coursesFilterSchema),
    onValidate({ payload }) {
      const result = coursesFilterSchema.safeParse(payload);
      return formatResult(result);
    },
});

I can definitely add this line schema: coursesFilterSchema and it start working. I guess the issue is the documentation or example from I take it miss this param. Would be nice to have it as required param

[edmundhung]

I am thinking about making the schema option more prominent by making it the first argument: #1069

What do you think?

[andrew-shpak]

if (!result.success) {
    return {
      // Create a submission result using the `report` helper
      result: report(submission, {
        error: formatResult(result),
      }),
    };
  }

Is it possible to introduce wrapper around this code? Base on my codebase, I think not only my, it will wrapped in some function

[andrew-shpak]

This is my wrapper

export function submissionFailure<Input>(
  result: ZodSafeParseError<Input>,
  submission: Submission
){
  const issues = result.error.issues;

  return {
    result: report(submission, {
      error: { issues },
    }),
  };
}

[edmundhung]

I would prefer not to introduce additional API that are just wrapper of existing one. What you have is fine and quite easy to maintain yourself.

[janhesters]

@edmundhung I have three questions about the new API:

1. How do you wire up shadcn/ui components with React Router? Specifically, how should FormOptionsProvider be configured on the server and on the client?
2. What about shadcn/ui’s new Field component? An example would be great.

This is my stab at it:

<Field data-invalid={fields.email.ariaInvalid}>
	<FieldLabel htmlFor={fields.email.id}>
		{t("emailLabel")}
	</FieldLabel>

	<InputGroup>
		<InputGroupInput
			aria-describedby={fields.email.ariaDescribedBy}
			aria-invalid={fields.email.ariaInvalid}
			id={fields.email.id}
			name={fields.email.name}
			placeholder={t("emailPlaceholder")}
			type="email"
		/>

		<InputGroupAddon>
			<MailIcon />
		</InputGroupAddon>
	</InputGroup>

	<FieldError
		errors={fields.email.errors}
		id={fields.email.errorId}
	/>
</Field>

3. How do you handle a React Router form with multiple intents when using z.discriminatedUnion, where each intent includes a literal and some data? Do you need separate forms with their own useForm instances, or is there a recommended pattern?

Here is an example. It is close to what I mean, but the second intent does not carry any data. My main question is how to handle multiple data-carrying intents in a single schema.

import type { SubmissionResult } from "@conform-to/react";
import { getInputProps, useForm } from "@conform-to/react";
import { getZodConstraint, parseWithZod } from "@conform-to/zod/v4";
import { APIError } from "better-auth";
import { TriangleAlertIcon } from "lucide-react";
import { useEffect } from "react";
import { Trans, useTranslation } from "react-i18next";
import { data, Form, href, redirect, useNavigation } from "react-router";
import { promiseHash } from "remix-utils/promise";
import * as z from "zod";

import { getIsOTPExpired } from "./+/check-otp-expiration.server";
import {
	destroyEmailCookie,
	getEmailFromCookie,
	setEmailCookie,
} from "./+/email-otp-cookie.server";
import { useCountdown } from "./+/use-countdown";
import type { Route } from "./+types/verify";
import { Alert, AlertDescription } from "~/components/ui/alert";
import { Button } from "~/components/ui/button";
import {
	Field,
	FieldDescription,
	FieldError,
	FieldGroup,
	FieldLabel,
	FieldSeparator,
	FieldSet,
} from "~/components/ui/field";
import {
	InputOTP,
	InputOTPGroup,
	InputOTPSeparator,
	InputOTPSlot,
} from "~/components/ui/input-otp";
import { Spinner } from "~/components/ui/spinner";
import { auth } from "~/lib/auth.server";
import { combineHeaders } from "~/lib/combine-headers.server";
import { getInstance } from "~/lib/i18next-middleware.server";
import { createToastHeaders, redirectWithToast } from "~/lib/toast.server";

export async function loader({ request, context }: Route.LoaderArgs) {
	const i18next = getInstance(context);
	const t = i18next.getFixedT(null, "auth", "verify");

	const email = await getEmailFromCookie(request);

	if (!email) {
		return await redirectWithToast("/login", {
			description: t("otpExpiredDescription"),
			title: t("otpExpired"),
			type: "error",
		});
	}

	const isOTPExpired = await getIsOTPExpired(email);

	if (isOTPExpired) {
		return await redirectWithToast(
			"/login",
			{
				description: t("otpExpiredDescription"),
				title: t("otpExpired"),
				type: "error",
			},
			{ headers: await destroyEmailCookie() },
		);
	}

	return {};
}

export const SEND_VERIFICATION_OTP_INTENT = "sendVerificationOtp" as const;
export const SIGN_IN_EMAIL_OTP_INTENT = "signInEmailOtp" as const;

const OTP_LENGTH = 6;

z.config({ jitless: true });
const otpSchema = z.object({
	intent: z.literal(SIGN_IN_EMAIL_OTP_INTENT),
	otp: z.string().length(OTP_LENGTH).default(""),
});

const schema = z.discriminatedUnion("intent", [
	z.object({ intent: z.literal(SEND_VERIFICATION_OTP_INTENT) }),
	otpSchema,
]);

export async function action({ request, context }: Route.ActionArgs) {
	const i18next = getInstance(context);
	const t = i18next.getFixedT(null, "auth", "verify");
	const formData = await request.formData();
	const submission = parseWithZod(formData, { schema });

	if (submission.status !== "success") {
		return data(submission.reply(), { status: 400 });
	}

	const email = await getEmailFromCookie(request);

	if (!email) {
		return await redirectWithToast("/login", {
			description: t("otpExpiredDescription"),
			title: t("otpExpired"),
			type: "error",
		});
	}

	switch (submission.value.intent) {
		case SIGN_IN_EMAIL_OTP_INTENT: {
			try {
				const { headers, destroyEmailCookieHeaders } = await promiseHash({
					destroyEmailCookieHeaders: destroyEmailCookie(),
					headers: auth.api
						.signInEmailOTP({
							body: { email, otp: submission.value.otp },
							returnHeaders: true,
						})
						.then((result) => result.headers),
				});

				return redirect(href("/onboarding"), {
					headers: combineHeaders(headers, destroyEmailCookieHeaders),
				});
			} catch (error) {
				if (error instanceof APIError) {
					const isTooManyAttempts = error.body?.code === "TOO_MANY_ATTEMPTS";
					const forbiddenStatus = 403;
					const badRequestStatus = 400;
					return data(
						submission.reply({
							fieldErrors: { otp: [error.body?.message ?? ""] },
						}),
						{
							status: isTooManyAttempts ? forbiddenStatus : badRequestStatus,
							...(isTooManyAttempts && { headers: await destroyEmailCookie() }),
						},
					);
				}

				throw error;
			}
		}
		case SEND_VERIFICATION_OTP_INTENT: {
			const [toastHeaders] = await Promise.all([
				createToastHeaders({
					description: t("newOtpSentDescription"),
					title: t("newOtpSent"),
					type: "success",
				}),
				auth.api.sendVerificationOTP({ body: { email, type: "sign-in" } }),
			]);

			return data(
				{ lastReset: new Date().toISOString() },
				{
					headers: combineHeaders(toastHeaders, await setEmailCookie(email)),
				},
			);
		}
	}
}

export default function VerifyRoute({ actionData }: Route.ComponentProps) {
	const { t } = useTranslation("auth", { keyPrefix: "verify" });

	const { secondsLeft, reset } = useCountdown(60);

	const lastReset = (actionData as { lastReset: string } | undefined)
		?.lastReset;

	useEffect(() => {
		if (lastReset) {
			reset();
		}
	}, [lastReset, reset]);

	const waitingToResend = secondsLeft !== 0;

	const navigation = useNavigation();
	const isResending =
		navigation.formData?.get("intent") === SEND_VERIFICATION_OTP_INTENT;
	const isVerifying =
		navigation.formData?.get("intent") === SIGN_IN_EMAIL_OTP_INTENT;
	const isSubmitting = isResending || isVerifying;

	const [form, fields] = useForm({
		constraint: getZodConstraint(otpSchema),
		lastResult:
			navigation.state === "idle"
				? (actionData as SubmissionResult<string[]> | undefined)
				: null,
		onValidate({ formData }) {
			return parseWithZod(formData, { schema: otpSchema });
		},
		shouldRevalidate: navigation.state === "idle" ? "onBlur" : undefined,
		shouldValidate: "onBlur",
	});

	return (
		<>
			<title>{t("meta.title")}</title>
			<div className="grid gap-4">
				<Form id={form.id} method="POST" noValidate onSubmit={form.onSubmit}>
					<FieldSet disabled={isSubmitting}>
						<FieldGroup>
							<div className="flex flex-col items-center gap-1 text-center">
								<h1 className="text-2xl font-bold">{t("title")}</h1>

								<p className="text-muted-foreground text-sm text-balance">
									{t("subtitle")}
								</p>
							</div>

							<Field data-invalid={!fields.otp.valid}>
								<FieldLabel className="sr-only" htmlFor={fields.otp.id}>
									{t("fieldLabel")}
								</FieldLabel>

								<div className="flex w-full justify-center">
									<InputOTP
										{...getInputProps(fields.otp, {
											ariaDescribedBy: fields.otp.descriptionId,
											type: "text",
										})}
										maxLength={OTP_LENGTH}
									>
										<InputOTPGroup className="gap-2 *:data-[slot=input-otp-slot]:rounded-md *:data-[slot=input-otp-slot]:border">
											<InputOTPSlot index={0} />
											<InputOTPSlot index={1} />
										</InputOTPGroup>

										<InputOTPSeparator />

										<InputOTPGroup className="gap-2 *:data-[slot=input-otp-slot]:rounded-md *:data-[slot=input-otp-slot]:border">
											<InputOTPSlot index={2} />
											<InputOTPSlot index={3} />
										</InputOTPGroup>

										<InputOTPSeparator />

										<InputOTPGroup className="gap-2 *:data-[slot=input-otp-slot]:rounded-md *:data-[slot=input-otp-slot]:border">
											<InputOTPSlot index={4} />
											<InputOTPSlot index={5} />
										</InputOTPGroup>
									</InputOTP>
								</div>

								<FieldDescription
									className="text-center"
									id={fields.otp.descriptionId}
								>
									{t("description")}
								</FieldDescription>

								<FieldError
									errors={fields.otp.errors}
									id={fields.otp.errorId}
								/>
							</Field>

							<Button
								name="intent"
								type="submit"
								value={SIGN_IN_EMAIL_OTP_INTENT}
							>
								{t("verifyButton")}
							</Button>
						</FieldGroup>
					</FieldSet>
				</Form>

				<FieldSeparator />

				<Form method="POST" onSubmit={() => reset()}>
					<FieldSet disabled={waitingToResend || isSubmitting}>
						<Alert>
							<TriangleAlertIcon />

							<AlertDescription>{t("alertDescription")}</AlertDescription>
						</Alert>

						<FieldDescription className="text-muted-foreground text-xs">
							<Trans
								components={{ 1: <b /> }}
								count={secondsLeft}
								i18nKey="verify.countdownMessage"
								ns="auth"
							/>
						</FieldDescription>

						<Button
							className="w-full"
							name="intent"
							type="submit"
							value={SEND_VERIFICATION_OTP_INTENT}
						>
							{isResending ? (
								<>
									<Spinner />
									{t("resendButtonSubmitting")}
								</>
							) : (
								t("resendButton")
							)}
						</Button>
					</FieldSet>
				</Form>
			</div>
		</>
	);
}

[edmundhung]

How do you wire up shadcn/ui components with React Router? Specifically, how should FormOptionsProvider be configured on the server and on the client?

I would recommend configuring it in your App component, especially if you plan to use custom metadata. Unlike React context, the custom types you extend are global, so it's best to place the provider at the top of your React tree. This ensures both the client and server share the same setup.

What about shadcn/ui’s new Field component? An example would be great.

What you have looks good to me. If you end up with a lot of forms or fields, you could take it a step further and make the Field component itself access the metadata via useField. That way, you won't need to repeat all the metadata props each time:

<Field name={fields.email.name}>
  <FieldLabel>{t("emailLabel")}</FieldLabel>
  <InputGroup>
    <InputGroupInput type="email" placeholder={t("emailPlaceholder")} />
    <InputGroupAddon><MailIcon /></InputGroupAddon>
  </InputGroup>
  <FieldError />
</Field>

To make this work, wrap the Field component in a React context that provides the name down the tree. Then components like FieldLabel, InputGroupInput, and FieldError can call useField internally to grab the right metadata.

This is just a personal preference, though. You could also use custom metadata to predefine prop mappings and spread them where needed.

How do you handle a React Router form with multiple intents when using z.discriminatedUnion, where each intent includes a literal and some data? Do you need separate forms with their own useForm instances, or is there a recommended pattern?

In general, I would recommend using separate forms with their own useForm hook. That keeps each form’s state isolated and avoids edge cases that can happen when multiple intents share a single form.

[janhesters]

@edmundhung Thank you so much for taking the time to answer all of my questions. I really appreciate it 🙏

[janhesters]

Man, the new conform API is soo clean. @edmundhung and team, great job! 👏 I wanted to post the final state of my code here with React Router V7 because its super clean and could safe others time figuring stuff out for themselves.

First, create the defineCustomMetadata function:

import type { BaseMetadata } from "@conform-to/react/future";
import type { ComponentProps } from "react";

import type { Input } from "~/components/ui/input";

export function defineCustomMetadata<FieldShape, ErrorShape>(
	metadata: BaseMetadata<FieldShape, ErrorShape>,
) {
	return {
		get inputProps() {
			return {
				"aria-describedby": metadata.ariaDescribedBy,
				"aria-invalid": metadata.ariaInvalid,
				id: metadata.id,
				name: metadata.name,
			} satisfies ComponentProps<typeof Input>;
		},
	};
}

I like to have a folder with all overwritten types, so create types/conform.d.ts:

import type { defineCustomMetadata } from "~/lib/define-custom-metadata";

declare module "@conform-to/react/future" {
	interface CustomMetadata<FieldShape, ErrorShape>
		extends ReturnType<typeof defineCustomMetadata<FieldShape, ErrorShape>> {}
}

In your layout, wrap it around the children:

export function Layout({ children }: { children: React.ReactNode }) {
	const data = useRouteLoaderData<typeof loader>("root");
	const { i18n } = useTranslation();
	const allowIndexing = data?.ENV.ALLOW_INDEXING !== "false";
	const loginMatch = useMatch("/login");
	const nonce = useNonce();
	const registerMatch = useMatch("/register");
	useToast(data?.toast);

	return (
		<html
			className={cn(
				data?.colorScheme ?? colorSchemes.system,
				"overscroll-none",
				// Need to hide overflow on auth screens
				loginMatch && "overflow-y-hidden",
				registerMatch && "overflow-y-hidden",
			)}
			dir={i18n.dir(i18n.language)}
			lang={i18n.language}
		>
			<head>
				<ClientHintCheck nonce={nonce} />
				<meta charSet="utf-8" />
				<meta content="width=device-width, initial-scale=1" name="viewport" />
				{allowIndexing ? null : (
					<meta content="noindex, nofollow" name="robots" />
				)}
				<Meta />
				<Links />
			</head>

			<body>
				<FormOptionsProvider
					defineCustomMetadata={defineCustomMetadata}
					shouldRevalidate="onBlur"
					shouldValidate="onBlur"
				>
					{children}
				</FormOptionsProvider>
				<script
					/**
					 * biome-ignore lint/security/noDangerouslySetInnerHtml: This is how
					 * you're supposed to set variables that are available on the client
					 * side with React Router.
					 */
					dangerouslySetInnerHTML={{
						__html: `window.ENV = ${JSON.stringify(data?.ENV ?? {})}`,
					}}
					nonce={nonce}
				/>
				<ScrollRestoration nonce={nonce} />
				<Scripts nonce={nonce} />
				<Toaster position="bottom-right" />
			</body>
		</html>
	);
}

Create a custom form validation helper that automatically returns data for bad results:

import { parseSubmission, report } from "@conform-to/react/future";
import { parseFormData } from "@mjackson/form-data-parser";
import type { MultipartParserOptions } from "@mjackson/multipart-parser";
import { data } from "react-router";
import type * as z from "zod";

/**
 * Validates form data from a request using a Zod schema.
 *
 * @param request - The HTTP request containing the form data to validate
 * @param schema - A Zod schema to validate the form data against
 * @param parserOptions - Optional multipart parser options for handling file
 * uploads
 * @returns A result object with either `{ success: true, data: T, submission: Submission }` on success
 * or `{ success: false, response: Response }` on validation failure
 *
 * @example
 * ```ts
 * import { z } from "zod";
 *
 * const loginSchema = z.object({
 *   email: z.string().email(),
 *   password: z.string().min(8),
 * });
 *
 * export async function action({ request }: Route.ActionArgs) {
 *   const result = await validateFormData(request, loginSchema);
 *
 *   if (!result.success) {
 *     // Returns a 400 response with validation errors
 *     return result.response;
 *   }
 *
 *   // Type-safe access to validated data
 *   const { email, password } = result.data;
 *
 *   // Process the validated data and return ...
 * }
 * ```
 */
export async function validateFormData<T extends z.ZodTypeAny>(
	request: Request,
	schema: T,
	parserOptions?: MultipartParserOptions,
) {
	const formData = parserOptions
		? await parseFormData(request, parserOptions)
		: await parseFormData(request);
	const submission = parseSubmission(formData);
	const result = schema.safeParse(submission.payload);

	if (!result.success) {
		/**
		 * You might be asking, why not `throw` here? When you `throw` the response,
		 * the `actionData` prop or `useActionData` hook will NOT be able to infer
		 * the TypeScript types correctly.
		 */
		return {
			response: data(
				{
					result: report(submission, {
						error: { issues: result.error.issues },
					}),
				},
				{ status: 400 },
			),
			success: false as const,
		};
	}

	return { data: result.data, submission, success: true as const };
}

Last but not least, use it!

import { useForm } from "@conform-to/react/future";
import { MailIcon } from "lucide-react";
import { Trans, useTranslation } from "react-i18next";
import { Form, href, Link, redirect, useNavigation } from "react-router";
import * as z from "zod";

import { setEmailCookie } from "./+/email-otp-cookie.server";
import type { Route } from "./+types/login";
import { Button, buttonVariants } from "~/components/ui/button";
import {
	Field,
	FieldDescription,
	FieldError,
	FieldGroup,
	FieldLabel,
	FieldSet,
} from "~/components/ui/field";
import {
	InputGroup,
	InputGroupAddon,
	InputGroupInput,
} from "~/components/ui/input-group";
import { Spinner } from "~/components/ui/spinner";
import { auth } from "~/lib/auth.server";
import { cn } from "~/lib/utils";
import { validateFormData } from "~/lib/validate-form-data";

z.config({ jitless: true });
export const schema = z.object({ email: z.email() });

export async function loader() {
	return {};
}

export async function action({ request }: Route.ActionArgs) {
	const result = await validateFormData(request, schema);

	if (!result.success) {
		return result.response;
	}

	const { email } = result.data;

	await auth.api.sendVerificationOTP({
		body: { email, type: "sign-in" },
	});

	return redirect(href("/verify"), { headers: await setEmailCookie(email) });
}

export default function LoginRoute({ actionData }: Route.ComponentProps) {
	const { t } = useTranslation("auth", { keyPrefix: "login" });
	const navigation = useNavigation();
	const { form, fields } = useForm({
		lastResult: actionData?.result,
		schema,
	});
	const isSubmitting = navigation.state === "submitting";

	return (
		<>
			<title>{t("meta.title")}</title>
			<Form method="POST" {...form.props}>
				<FieldSet disabled={isSubmitting}>
					<FieldGroup>
						<div className="flex flex-col items-center gap-1 text-center">
							<h1 className="text-2xl font-bold">{t("title")}</h1>

							<p className="text-muted-foreground text-sm text-balance">
								{t("subtitle")}
							</p>
						</div>

						<Field data-invalid={fields.email.ariaInvalid}>
							<FieldLabel htmlFor={fields.email.id}>
								{t("emailLabel")}
							</FieldLabel>

							<InputGroup>
								<InputGroupInput
									{...fields.email.inputProps}
									autoComplete="email"
									placeholder={t("emailPlaceholder")}
									type="email"
								/>

								<InputGroupAddon>
									<MailIcon />
								</InputGroupAddon>
							</InputGroup>

							<FieldError
								errors={fields.email.errors}
								id={fields.email.errorId}
							/>
						</Field>
					</FieldGroup>

					<Field>
						<Button type="submit">
							{isSubmitting ? (
								<>
									<Spinner /> {t("submitButtonSubmitting")}
								</>
							) : (
								t("submitButton")
							)}
						</Button>
					</Field>

					<Field>
						<FieldDescription className="text-center">
							<Trans
								components={{
									signup: (
										<Link
											className={cn(
												buttonVariants({ variant: "link" }),
												"text-muted-foreground max-h-min p-0 hover:text-primary",
											)}
											to={href("/register")}
										/>
									),
								}}
								i18nKey="login.signupCta"
								ns="auth"
							/>
						</FieldDescription>
					</Field>
				</FieldSet>
			</Form>
		</>
	);
}

[janhesters]

@edmundhung Reading through all the comments here, I'm confused about this 👇

For most users, what's really needed are just two things: name and defaultValue. If you have lots of inputs, you will likely wrap them in a custom component anyway, so you only need to configure it once.

Don't you usually also need things like id, aria-describedby={fields.name.ariaDescribedBy} etc.? To me, the getInputProps helper was always super useful, so I'm confused why this version is removing it ...

[edmundhung]

It's because getInputProps was mainly designed for native inputs. When used with UI libraries, it often gives a false sense of correctness since their prop conventions (like required vs isRequired) can differ.

If you are building your own form components, I would suggest wiring them up explicitly instead. Or, if you prefer to keep them decoupled from Conform, you can use the new <FormOptionsProvider /> introduced in v1.12.0 to define custom metadata that maps cleanly to your component props. That way you can keeps things type-safe without depending on additional helpers like getInputProps.

[edmundhung]

There are also cases where libraries like React Aria already handle accessibility attributes and IDs internally. In those situations, using getInputProps on top of it can actually make things worse with non matching ids.

[janhesters]

Oooh that makes sense. In that case, the API is actually pretty good! I love it! 🔥 Thank you 🙏

[janhesters]

@edmundhung

That's fair. The server side is definitely a bit messier to work with right now. From what you wrote, it sounds like you are looking for an experience closer to parseWithZod in v1?

Second this! We have to go from this:

export async function action({ request }: Route.ActionArgs) {
	const formData = await request.formData();
	const submission = parseWithZod(formData, { schema });

	if (submission.status !== "success") {
		return data(submission.reply(), { status: 400 });
	}

	const { email } = submission.value;

	await auth.api.sendVerificationOTP({
		body: { email, type: "sign-in" },
	});

	return redirect(href("/verify"), { headers: await setEmailCookie(email) });
}

To this:

export async function action({ request }: Route.ActionArgs) {
	const formData = await request.formData();
	const submission = parseSubmission(formData);
	const result = schema.safeParse(submission.payload);

	if (!result.success) {
		return data(
			{
				result: report(submission, { error: { issues: result.error.issues } }),
			},
			{ status: 400 },
		);
	}

	const { email } = result.data;

	await auth.api.sendVerificationOTP({
		body: { email, type: "sign-in" },
	});

	return redirect(href("/verify"), { headers: await setEmailCookie(email) });
}

I think the new API is more ugly than the old one due to the boilerplate.

Buuut one could create a custom wrapper. Here is my stab at it:

function validateFormData<T extends z.ZodTypeAny>(
	formData: FormData,
	schema: T,
) {
	const submission = parseSubmission(formData);
	const result = schema.safeParse(submission.payload);

	if (!result.success) {
		return {
			response: data(
				{
					result: report(submission, {
						error: { issues: result.error.issues },
					}),
				},
				{ status: 400 },
			),
			success: false as const,
		};
	}

	return { data: result.data, success: true as const };
}

export async function action({ request }: Route.ActionArgs) {
	const formData = await request.formData();
	const result = validateFormData(formData, schema);

	if (!result.success) {
		return result.response;
	}

	const { email } = result.data;

	await auth.api.sendVerificationOTP({
		body: { email, type: "sign-in" },
	});

	return redirect(href("/verify"), { headers: await setEmailCookie(email) });
}

[edmundhung]

I understand where you are coming from. The new API can look a bit more verbose at first. But this design do aims for a better balance between clarity and flexibility. It keeps the logic explicit, so you can integrate different schema libraries or custom validation flows without Conform making assumptions for you.

Rather than adding another higher-level helper, it’s often cleaner to define your own small abstraction around parseSubmission and report. That way, you keep full control while still keeping your code concise.

For example, I think #1014 (reply in thread) is not a bad idea. 👍🏼

[edmundhung]

Just notice you added an example. You might need to add another argument to support async validation. But if you don't need it, that looks great!

[janhesters]

@edmundhung Yes. I also edited my other questions as I play around with this API. Thank you for all the help, conform is my favorite form library, and I'm super excited for this next version.

[janhesters]

For any one interested and also using React Router v7, I ended up with this abstraction:

import { parseSubmission, report } from "@conform-to/react/future";
import { parseFormData } from "@mjackson/form-data-parser";
import type { MultipartParserOptions } from "@mjackson/multipart-parser";
import { data } from "react-router";
import type * as z from "zod";

export async function validateFormData<T extends z.ZodTypeAny>(
	request: Request,
	schema: T,
	parserOptions?: MultipartParserOptions,
) {
	const formData = parserOptions
		? await parseFormData(request, parserOptions)
		: await parseFormData(request);
	const submission = parseSubmission(formData);
	const result = schema.safeParse(submission.payload);

	if (!result.success) {
		return {
			response: data(
				{
					result: report(submission, {
						error: { issues: result.error.issues },
					}),
				},
				{ status: 400 },
			),
			success: false as const,
		};
	}

	return { data: result.data, success: true as const };
}

It can also handle file uploads for encType="multipart/form-data".

[transparent-citizen]

With exactOptionalPropertyTypes enabled,

✅ a missing lastResult works:

const { fields, form } = useForm({
	schema,
});

✅ a null lastResult works:

const { fields, form } = useForm({
	lastResult: null,
	schema,
});

❌ an undefined lastResult throws a type error:

const { fields, form } = useForm({
	lastResult: undefined,
	schema,
});

Argument of type '{ lastResult: undefined; schema: z.ZodObject<{ example: z.ZodOptional<z.ZodString>; }, z.core.$strip>; }' is not assignable to parameter of type 'FormOptions<{ example?: string | undefined; }, string, { example?: string | undefined; }>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
  Type '{ lastResult: undefined; schema: z.ZodObject<{ example: z.ZodOptional<z.ZodString>; }, z.core.$strip>; }' is not assignable to type '{ id?: string; key?: string; schema?: StandardSchemaV1<{ example?: string | undefined; }, { example?: string | undefined; }>; defaultValue?: NoInfer<{ example?: string | null | undefined; } | null | undefined>; ... 7 more ...; onBlur?: BlurHandler; }' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
    Types of property 'lastResult' are incompatible.
      Type 'undefined' is not assignable to type 'SubmissionResult<string> | null'.ts(2379)

[edmundhung]

Thanks for flagging. Looks like I really need to spend sometime figuring out how to test this properly.

I tried enabling it in the project yesterday but find it really painful as it force me doing a lot more check that doesn't seems necessary, especially in library code 🙃 I will go through all the types over the weekend to see if there is more I missed.

[transparent-citizen]

My apologies for the pain! 😅 I found it easier to start projects with that setting rather than retrofitting it. Just to give details to my use case:

If you return the result of a report from an action, react-router's actionData from the route component will be typed as such:

actionData: {
    lastResult: SubmissionResult<string, string | number | boolean | null>;
} | undefined

The | undefined at the end is due to the fact that you might just view the form via a GET request without a submission. This means that you will get into a situation where you may have to pass undefined to lastResult explicitly:

const { form, fields } = useForm({
	lastResult: actionData?.lastResult,
	schema,
});

Abusing object spreading is a workaround that avoids the type error:

const { form, fields } = useForm({
	...actionData,
	schema,
});

The downside being that as soon as actionData contains more than just lastResult, some data may accidentally bleed into the useForm options.

[transparent-citizen]

In terms of API design, what is this supposed to do?

report(submission, {
    reset: true,
    intendedValue: {
        foo: "bar"
    }
});

The current behavior, as far as I can tell, is to silently ignore intendedValue and only process the reset bit, that is, reset the form to defaultValue and clear form state such as errors.

Wouldn't it feel more reasonable to perform the state reset, but reset the field values to intendedValue as opposed to defaultValue?

[edmundhung]

Maybe? intendedValue was designed for progressive enhancement where you need to tell Conform what the form value that the received intent expects, and that's why it is called that way.

What is your usecase? Why would you want it over the defaultValue passed to useForm?

[edmundhung]

I think the idea is reasonable. Just curious how you are using intendedValue right now as I haven't really think through how people will use it.

[transparent-citizen]

I have an input that honors the user's number locale.

For instance, when a user with the en-GB locale enters "10000000" into that input, submitting will have the server transform it to "10,000,000" and send it to the client as new value using intendedValue.

I found this to enable a higher degree of reactivity in forms, since defaultValue concerns itself only with the initial render, whereas setting intendedValue can be used to control subsequent renders.

[edmundhung]

Got an initial implementation of it in #1079 that you can test. I wonder if intendedValue is clear enough or I should figure out a different name.

[transparent-citizen]

Thank you! I left a comment in the PR.

Quoting the docs for intendedValue:

The intended form values to track what the form should contain vs. what was actually submitted.

To me, this alone does not clearly convey that conform uses this value to set the field values of the next state, so the question "intended for what?" may arise. Maybe something like nextValue could clear that up a little, but of course feel free to bikeshed.

[janhesters]

@edmundhung I think I found a bug:

Optional <input type="file"> is treated as required even with Zod v4 optional() / nullish() / union(undefined)

I’ve hit a blocker with file inputs being treated as required even when the schema explicitly allows them to be omitted.

Environment

• @conform-to/react: 1.13.1
• @conform-to/zod: 1.13.1
• zod: 4.1.12 (Zod v4 API)
• Router runtime: react-router 7.9.4
• React: 19.2.0

What I’m trying to do

Make an avatar upload optional. If the user does not pick a file, validation should pass and image should be undefined.

Schema attempts

I tried all of the following with Zod v4:

// 1) union with undefined
image: z.union([z.file().max(oneMB).mime("image/*"), z.undefined()])

// 2) optional
image: z.file().max(oneMB).mime("image/*").optional()

// 3) nullish
image: z.file().max(oneMB).mime("image/*").nullish()

Actual vs expected

Actual

• Submitting the form without selecting a file yields an error on image complaining about undefined / "Expected File" / "Required" on the client.
• It only passes when a file is selected.

Expected

• Submitting the form without selecting a file should be valid and yield image === undefined in the action.
• Validation should only run the max and mime checks when a file is present.

Repro details

• When no file is chosen, the browser omits the field from FormData entirely, so formData.get('image') is null.
• The Conform fields.image.inputProps includes the correct name, and the server uses validateFormData(request, schema) with the v4 schema.
• Regardless of using union(undefined), optional(), or nullish(), the result is a validation error for image unless a file is picked.

Minimal repro (server + client)

Server action and schema (Zod v4)

import * as z from "zod";
import { validateFormData } from "@conform-to/zod"; // same behavior with our helper calling this

const oneMB = 1_000_000;

const schema = z.object({
  image: z.file().max(oneMB).mime("image/*").optional(), // same result with nullish() or union(undefined)
  name: z.string().min(3).max(72),
});

export async function action({ request }: { request: Request }) {
  const result = await validateFormData(request, schema);

  if (!result.success) {
    return result.response; // includes an error for `image` when no file selected
  }

  // result.data.image should be File | undefined
  return { ok: true };
}

Client form wiring

import { useForm } from "@conform-to/react/future";

const { form, fields } = useForm({
  lastResult: actionData?.result,
  schema, // passed as above
});

return (
  <Form {...form.props}>
    {/* ...other fields... */}
    <input type="file" {...fields.image.inputProps} />
    {/* error renders from fields.image.errors */}
    <button type="submit">Save</button>
  </Form>
);

I also verified that when no file is selected the FormData has no image entry at all, which should map cleanly to undefined and satisfy optional().

What I suspect

• Either @conform-to/zod’s adapter for Zod v4 z.file() is not treating missing file fields as undefined, or
• The presence/required inference for file fields is derived from the base type (z.file()) rather than the decorated type (optional()/nullish()/union(undefined)), causing Conform to mark the field as required or to coerce null to a failing value before the optional branch is considered.

---

Full app snippets for context

user.tsx:

import { useForm } from "@conform-to/react/future";
import { Img } from "openimg/react";
import { useTranslation } from "react-i18next";
import { Form, href, redirect, useNavigation } from "react-router";
import * as z from "zod";

import { authContext } from "../+/authentication-middleware.server";
import type { Route } from "./+types/user";
import {
	AvatarUpload,
	AvatarUploadDescription,
	AvatarUploadInput,
	AvatarUploadPreview,
} from "~/components/avatar-upload";
import { Avatar, AvatarFallback, AvatarImage } from "~/components/ui/avatar";
import { Button } from "~/components/ui/button";
import {
	Field,
	FieldDescription,
	FieldError,
	FieldGroup,
	FieldLabel,
	FieldSet,
} from "~/components/ui/field";
import { Input } from "~/components/ui/input";
import { Spinner } from "~/components/ui/spinner";
import { auth } from "~/lib/auth.server";
import { getUserImgSrc } from "~/lib/get-img-src";
import { uploadProfileImage } from "~/lib/storage.server";
import { validateFormData } from "~/lib/validate-form-data";
import { LOGIN_WITH_EMAIL_INTENT } from "~/routes/_auth/login";

export function loader({ context }: Route.LoaderArgs) {
	const { user } = context.get(authContext);
	return { user };
}

export const ONBOARD_USER_ACCOUNT_INTENT = "onboardUserAccount" as const;

const MIN_NAME_LENGTH = 3;
const MAX_NAME_LENGTH = 72;

const oneMB = 1_000_000;

z.config({ jitless: true });
const schema = z.object({
	image: z.union([z.file().max(oneMB).mime("image/*"), z.undefined()]),
	name: z.string().min(MIN_NAME_LENGTH).max(MAX_NAME_LENGTH),
});

export async function action({ request, context }: Route.ActionArgs) {
	const result = await validateFormData(request, schema);

	if (!result.success) {
		return result.response;
	}

	console.log(result.data);
	const { user } = context.get(authContext);
	const image = result.data.image
		? await uploadProfileImage(user.id, result.data.image)
		: (user?.image ?? "");
	await auth.api.updateUser({ body: { image, name: result.data.name } });

	// return redirect(href("/onboarding/organization"));
	return { result: undefined };
}

export default function UserAccountRoute({
	actionData,
	loaderData,
}: Route.ComponentProps) {
	const { t } = useTranslation("onboarding", { keyPrefix: "user" });

	const { form, fields } = useForm({
		lastResult: actionData?.result,
		schema,
	});

	const navigation = useNavigation();
	const isSubmitting = navigation.state === "submitting";

	return (
		<>
			<title>{t("title")}</title>

			<Form {...form.props}>
				<FieldSet disabled={isSubmitting}>
					<FieldGroup>
						<div className="flex flex-col gap-1">
							<h1 className="text-2xl font-bold">{t("heading")}</h1>

							<p className="text-muted-foreground text-sm text-pretty">
								{t("subtitle")}
							</p>
						</div>

						<Field data-invalid={fields.name.ariaInvalid}>
							<FieldLabel htmlFor={fields.name.id}>{t("nameLabel")}</FieldLabel>

							<FieldDescription id={fields.name.descriptionId}>
								{t("nameDescription")}
							</FieldDescription>

							<Input
								{...fields.name.inputProps}
								defaultValue={loaderData.user.name}
								placeholder={t("namePlaceholder")}
							/>

							<FieldError
								errors={fields.name.errors}
								id={fields.name.errorId}
							/>
						</Field>

						<Field>
							<FieldLabel htmlFor={fields.image.id}>
								{t("profilePhotoLabel")}
							</FieldLabel>

							<FieldDescription id={fields.image.descriptionId}>
								{t("profilePhotoDescription")}
							</FieldDescription>

							<AvatarUpload>
								<div className="flex items-center gap-x-4 md:gap-x-8">
									<Avatar className="size-16 md:size-24 rounded-lg">
										<AvatarImage asChild>
											<AvatarUploadPreview
												alt={t("profilePhotoPreviewAlt")}
												className="size-16 md:size-24 rounded-lg"
												height={96}
												width={96}
											/>
										</AvatarImage>

										<AvatarFallback className="border-border dark:bg-input/30 size-16 md:size-24 rounded-lg border">
											<Img
												className="size-16 md:size-24 rounded-lg"
												height={96}
												src={getUserImgSrc(loaderData.user.image)}
												width={96}
											/>
										</AvatarFallback>
									</Avatar>

									<div className="flex flex-col gap-2">
										<AvatarUploadInput {...fields.image.inputProps} />

										<AvatarUploadDescription>
											{t("profilePhotoFormats")}
										</AvatarUploadDescription>
									</div>
								</div>

								<FieldError
									errors={fields.image.errors}
									id={fields.image.errorId}
								/>
							</AvatarUpload>
						</Field>

						<Field>
							<Button
								name="intent"
								type="submit"
								value={LOGIN_WITH_EMAIL_INTENT}
							>
								{isSubmitting ? (
									<>
										<Spinner /> {t("saving")}
									</>
								) : (
									t("save")
								)}
							</Button>
						</Field>
					</FieldGroup>
				</FieldSet>
			</Form>
		</>
	);
}

avatar-upload.tsx:

import { Img } from "openimg/react";
import type {
	ChangeEvent,
	ChangeEventHandler,
	ComponentProps,
	ReactNode,
} from "react";
import {
	createContext,
	useCallback,
	useContext,
	useEffect,
	useState,
} from "react";
import { useTranslation } from "react-i18next";

import { Input } from "~/components/ui/input";
import { cn } from "~/lib/utils";

function formatBytes(bytes: number, decimals = 2) {
	if (bytes === 0) return "0 Bytes";

	const k = 1024;
	const dm = Math.max(decimals, 0);
	const sizes = ["Bytes", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"];

	const index = Math.floor(Math.log(bytes) / Math.log(k));

	return `${Number.parseFloat((bytes / k ** index).toFixed(dm))} ${sizes[index] ?? "Bytes"}`;
}

type AvatarUploadContextType = {
	file: File | undefined;
	handleFileChange: ChangeEventHandler<HTMLInputElement>;
	handleRemoveFile: () => void;
	inputKey: number;
	previewUrl: string;
};

const AvatarUploadContext = createContext<AvatarUploadContextType>(
	undefined as never,
);

export function AvatarUpload({
	children,
	maxFileSize,
}: {
	children: ReactNode | ((props: { error: string }) => ReactNode);
	maxFileSize?: number;
}) {
	const { t } = useTranslation("translation", { keyPrefix: "avatarUpload" });
	const [error, setError] = useState("");
	const [file, setFile] = useState<File | undefined>();
	const [inputKey, setInputKey] = useState(Date.now());
	const [previewUrl, setPreviewUrl] = useState("");

	const handleFileChange = useCallback(
		(event: ChangeEvent<HTMLInputElement>) => {
			const currentFile = event.target.files?.[0];

			if (currentFile) {
				if (typeof maxFileSize === "number" && currentFile.size > maxFileSize) {
					setError(
						t("fileSizeError", {
							fileName: currentFile.name,
							maxSize: formatBytes(maxFileSize),
						}),
					);
					// Clear the invalid file from the input.
					event.target.value = "";
					return;
				}

				setError("");
				const url = URL.createObjectURL(currentFile);
				setPreviewUrl(url);
				setFile(currentFile);
			} else {
				setPreviewUrl("");
				setFile(undefined);
			}
		},
		[maxFileSize, t],
	);

	const handleRemoveFile = useCallback(() => {
		setError("");
		setFile(undefined);
		setPreviewUrl("");
		// By changing the key, we force React to re-mount the input,
		// which is the cleanest way to reset an uncontrolled component.
		setInputKey(Date.now());
	}, []);

	useEffect(() => {
		return () => {
			if (previewUrl) {
				URL.revokeObjectURL(previewUrl);
			}
		};
	}, [previewUrl]);

	return (
		<AvatarUploadContext.Provider
			value={{ file, handleFileChange, handleRemoveFile, inputKey, previewUrl }}
		>
			{typeof children === "function" ? children({ error }) : children}
		</AvatarUploadContext.Provider>
	);
}

function useAvatarUpload() {
	return useContext(AvatarUploadContext);
}

export function AvatarUploadPreview({
	src,
	...props
}: ComponentProps<typeof Img>) {
	const { previewUrl } = useAvatarUpload();

	return <Img src={previewUrl || src} {...props} />;
}

export function AvatarUploadInput({
	onChange,
	...props
}: ComponentProps<"input">) {
	const { handleFileChange, inputKey } = useAvatarUpload();

	function handleChange(event: ChangeEvent<HTMLInputElement>) {
		handleFileChange(event);
		onChange?.(event);
	}

	return (
		<Input key={inputKey} type="file" {...props} onChange={handleChange} />
	);
}

export function AvatarUploadDescription({
	className,
	...props
}: ComponentProps<"p">) {
	return (
		<p className={cn("text-muted-foreground text-xs", className)} {...props} />
	);
}

[edmundhung]

Sorry again for the late reply.

I just give it a test and notice 2 things:

• Your image schema is not optional (which I think is just a typo)
• Zod .mime check doesn't seems to support image/*. I tried not wrapping the schema with coerceFormValue but zod is still complaining about invalid input until I change it to image/png.

Once I fixed these two things, it seems to work as expected. Hope this helps :)

[janhesters]

Thank you!

[janhesters]

@edmundhung This works btw!

Also, just putting it on your radar, if you have two schemas, you need to coerce both the client schema and the server schema. Now idea, if this is intentional.

import { parseSubmission, report, useForm } from "@conform-to/react/future";
import { coerceFormValue } from "@conform-to/zod/v4/future";
import { parseFormData } from "@remix-run/form-data-parser";
import { data, Form } from "react-router";
import * as z from "zod";

import type { Route } from "./+types/example";

const updateSchema = z.object({
  image: z
    .file()
    .mime(["image/png", "image/jpeg", "image/jpg", "image/webp"])
    .optional(),
  intent: z.literal("update"),
});

const deleteSchema = z.object({
  intent: z.literal("delete"),
});

// ❗️ First coercion
const schema = coerceFormValue(
  z.discriminatedUnion("intent", [updateSchema, deleteSchema]),
);

export async function action({ request }: Route.ActionArgs) {
  const formData = await parseFormData(request);
  const submission = parseSubmission(formData);
  const result = schema.safeParse(submission.payload);

  if (!result.success) {
    return data(
      {
        result: report(submission, {
          error: { issues: result.error.issues },
        }),
        success: false,
        type: undefined,
      },
      {
        status: 400,
      },
    );
  }

  if (result.data.intent === "delete") {
    return { result: undefined, success: true, type: "delete" as const };
  }

  return { result: undefined, success: true, type: "update" as const };
}

function UpdateForm({
  actionData,
}: {
  actionData?: Route.ComponentProps["actionData"];
}) {
  const { form, fields } = useForm({
    lastResult: actionData?.result,
    // ❗️ Second coercion
    schema: coerceFormValue(updateSchema),
  });

  return (
    <Form
      className="flex flex-col gap-4"
      encType="multipart/form-data"
      method="POST"
      {...form.props}
    >
      <input type="file" {...fields.image.inputProps} />

      <button name="intent" type="submit" value="update">
        Update
      </button>

      {fields.image.errors && (
        <p className="text-red-500" id={fields.image.errorId}>
          {fields.image.errors.join(", ")}
        </p>
      )}
    </Form>
  );
}

function DeleteForm({
  actionData,
}: {
  actionData?: Route.ComponentProps["actionData"];
}) {
  const { form } = useForm({
    lastResult: actionData?.result,
    schema: deleteSchema,
  });

  return (
    <Form className="flex flex-col gap-4" method="POST" {...form.props}>
      <button
        className="bg-red-500 text-white px-4 py-2 rounded"
        name="intent"
        type="submit"
        value="delete"
      >
        Delete
      </button>
    </Form>
  );
}

export default function Example({ actionData }: Route.ComponentProps) {
  return (
    <main className="p-4">
      <div className="mx-auto max-w-sm space-y-8">
        <div>
          <h2 className="font-bold mb-4">Update Form</h2>
          <UpdateForm actionData={actionData} />
          {actionData?.success && actionData.type === "update" && (
            <p className="text-green-500 mt-2">
              Update submitted successfully!
            </p>
          )}
        </div>

        <div>
          <h2 className="font-bold mb-4">Delete Form</h2>
          <DeleteForm actionData={actionData} />
          {actionData?.success && actionData.type === "delete" && (
            <p className="text-green-500 mt-2">
              Delete submitted successfully!
            </p>
          )}
        </div>
      </div>
    </main>
  );
}

[edmundhung]

You can also wrap updateSchema and deleteSchema with coerceFormValue separately. That way you don't need to inline it in the component.

[edmundhung]

Like this:

const updateSchema = coerceFormValue(
  z.object({
    image: z
      .file()
      .mime(["image/png", "image/jpeg", "image/jpg", "image/webp"])
      .optional(),
    intent: z.literal("update"),
  })
);

const deleteSchema = coerceFormValue(
  z.object({
    intent: z.literal("delete"),
  })
);

const schema = z.discriminatedUnion("intent", [updateSchema, deleteSchema]);

[janhesters]

@edmundhung Are there needs for better prop helpers for the form? I think in order to make it accessible, we still need to wire up a lot of attributes (in other words, is form.props "underpowered")?

			<Form
				encType="multipart/form-data"
				method="POST"
				{...form.props}
				aria-describedby={
					form.errors && form.errors.length > 0
						? `${form.descriptionId} ${form.errorId}`
						: form.descriptionId
				}
				aria-invalid={form.errors && form.errors.length > 0 ? true : undefined}
			>
				<FieldSet disabled={isSubmitting}>
					<FieldGroup>
						<div className="flex flex-col gap-1">
							<h1 className="text-2xl font-bold">{t("heading")}</h1>
							<p
								className="text-muted-foreground text-sm text-pretty"
								id={form.descriptionId}
							>
								{t("subtitle")}
							</p>
						</div>

						{form.errors && form.errors.length > 0 && (
							<Alert id={form.errorId} variant="destructive">
								<AlertTitle>
									{t("errors.createOrganizationFailedTitle")}
								</AlertTitle>

								<AlertDescription>
									{t("errors.createOrganizationFailedDescription")}
								</AlertDescription>
							</Alert>
						)}

[edmundhung]

Yes! I think the form metadata should at least offer form.ariaDescribedBy and form.ariaInvalid just like the field metadata. It's indeed tempting to include both in the form.props but I am a bit worry about over specifying props as UI libraries might manages their own aria attributes (e.g. react aria components)

[edmundhung]

Interested in submitting a PR? You just need to implement it here. You can find the implementation of the field metadata on the same file.

[janhesters]

@edmundhung

I am a bit worry about over specifying props as UI libraries might manages their own aria attributes

Very legit.

Would it maybe make sense to add another function like defineCustomMetadata (e.g. defineCustomFormMetadata), so that you can then say form.customProps or whatever? That way the default stays "non-opinionated" while giving users the opportunity to customize it.

[edmundhung]

I think yes. I will be working on custom state next and custom form metadata will be a part of it.

[DarkstarXDD]

Hey, I am a bit confused about some of the changes that's happening on the future export.

So is the parseWithZod() no longer valid? Because in the examples for the future export I am only seeing the report() function in the server side code.

And if parseWithZod() is no longer valid, and I have to manually use safeParse() from Zod on the data I get from parseSubmission(), then that means I no longer get the empty string stripping and coercing feature we had with parseWithZod() on the server side? Or am I missing something?

Edit: Ok I think things are bit clear for me now, though it took a bit of trial and error to actually figue out it out.

So the idea now is that we pass the Zod schema as the first argument to the useForm(), and then we only need to pass the form.props.onSubmit to the <form>. That alone takes care of client side validation.

If not, we can also use the coerceFormValue() to create a new schema with the stripping and coerce features parseWithZod() had. Then we can use that enhanced schema as enhancedSchema.safeParse(data) and do the validation. Then we need to use formResult() to convert that Zod validation result into a format Conform expects, so that we can pass it to onValidate in the useForm().

At least that's how I think the pattern looks like in the client. Need to check how the server side looks later.

[edmundhung]

Sorry for the late reply! What you found is mostly correct. If you wanna restore the behavior of parseWithZod, you will need to first enhanced your schema with coerceFormValue.

With the latest future version, parseSubmission will strips empty value for you. So coerceFormValue is only needed if you want automatic type coercion. e.g. string -> number. This is totally optional as you can always handle this yourself by adding a preprocess step in your schema.

This applies to both client and server side.

[edmundhung]

formatResult is necessary only if you want to customize how error is formatted. You can passed the zod error object to report directly now. You can find some examples in the examples directory of the repository. They are all updated to use the future APIs

[DarkstarXDD]

Got it. Thank you for the response!

[ikoamu]

Can virtual scrolling be achieved with the new useForm?
I was very interested after looking at #1007.

[edmundhung]

Hi @ikoamu, I am designing a new component that should enable that. Let me know if you could give the pre-release a try. 👍🏼

[tyforcode]

The new future exports have been going pretty well so far. Thanks for the updates!

One missing piece that's been tripping me up is not having a form.value equivalent at the root level to listen to inline changes. useFormData seems to be the way around this, but it seems to crash with the error: No form context found; Have you render a <FormProvider /> with the corresponding form context? unless it's already wrapped in a FormProvider (which won't happen at the top level).

It happens even when provided the same formId passed to useForm. Are there any thoughts on how to work with this?

[edmundhung]

Hi @tyforcode, useFormData doesn't rely on the <FormProvider /> so I am not sure why you are getting that. Do you mind share a bit more on how your form is setup?

[tyforcode]

Hmm testing on a fresh project I can't seem to recreate this issue and it works as intended. There must be something with my current setup... If something comes up though and I'm able to reproduce this, I'll put another comment here. Thanks!