Future Export: The road to v2

[edmundhung]

It's been over a year since Conform's first major release and we have learned a lot since then. We have seen where people get stuck, where the API causes confusion, and where the complexity starts to pile up. We want to fix those things — but without making the code more complicated.

Over the past 6 months, we have been exploring a new model. We believe it's simpler, more flexible, and easier to reason about without giving up type safety or progressive enhancement. But instead of rushing to v2, we want to validate these ideas with the community first.

That's what the new future export is for:

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

This is a place for experimental APIs we're ready to share but still refining. They are opt-in, and you can adopt them gradually. As these APIs mature, we'll offer migration guides and eventually promote them as the new defaults in v2. Until then, they might include breaking changes in minor versions. So we recommend locking your version range to patch when using them.

We're planning to roll out the first public release of the future export soon, and we're sharing this early so it's not a surprise when it lands — and to avoid confusion when you see new APIs appear.

First up

The first future API is useControl — a new hook that helps you integrate custom inputs with Conform. Compared to useInputControl, it offers a more flexible setup with better support for multi select, file inputs and checkbox groups.

The first public release of this API is just a few days away. We are sharing this announcement early so you can get an idea of what's coming and let us know what you think.

(Update: released in v1.7.0)

What's coming next

In the coming weeks, you will see:

• A useFormData hook to subscribe to form data and compute derived state (Update: released in v1.8.0)
• A redesigned useForm hook with more control over form state and metadata
• Simplified parse helpers with better async validation support

All of these will be released through the future export and get their own write-up.

If you try any of these APIs, we would love to hear how they go — what works, what doesn't, and what could be better. Your feedback will help shape the next major version of Conform.

[muco-rolle]

Awesome. I'm excited to explore those new APIs. It would also be great to have something like watch and subscribe APIs, maybe that's what we'll get with useFormData.

[edmundhung]

The useFormData hook is just released in v1.8.0. Learn more here.

[aaronadamsCA]

I wonder if this opens up a path to progressively enhancing a form to auto-submit when certain values are changed. Any thoughts?

Right now our typical approach is a Headless UI component with an onChange handler, but this means the component is non-interactive until hydration.

If we could use a standard <select> or <input type="checkbox"> instead, I wonder if the user could interact before hydration, and then we could auto-submit the form when hydration is complete.

I gave this a quick try using useFormData, isDirty, and useEffect without success, but it's entirely possible I did something wrong.

[aaronadamsCA]

I still think I'd prefer GET form fields to always track changes to defaultValue and lastResult.initialValue.

key is a great idea that formalizes the "id hack" without forcing an unstable ID, but it still feels like a hack 🙃

To add a few more ideas:

• useForm({ eager: true }) could be a simple solution.
• useForm({ shouldUpdate: (name) => name === "query" }) could offer more control.
• useForm({ method: "GET", lastResult }) could lead to an ideal solution.

On this last idea: if a route has a GET form that acts on itself, every page load is a form submission, even the first one! Given that, I think the "right" solution is to never set defaultValue, always set lastResult, and always update field values when lastResult changes. I could imagine method: "GET" automatically enabling that last part.

As a bonus, adding method to form metadata would mean I could get every <form> prop from useFormMetadata().

[aaronadamsCA]

If it helps add clarity, this is more or less what we're doing now:

export function loader({ request }: LoaderFunctionArgs): Schema {
  const { searchParams } = new URL(request.url);
  const submission = parseWithZod(searchParams, { schema });
  invariant(submission.status === "success", "Invalid search params");
  return submission.value;
}

export default function Route() {
  const { query } = useLoaderData<typeof loader>();

  return (
    <Form method="GET">
      <input key={query} name="query" defaultValue={query} />
    </Form>
  );
}

And how I think we'd like to be able to do it instead:

export function loader({ request }: LoaderFunctionArgs): SubmissionResult {
  const { searchParams } = new URL(request.url);
  return parseWithZod(searchParams, { schema }).reply();
}

export default function Route() {
  const lastResult = useLoaderData<typeof loader>();
  const [form, fields] = useForm<Schema>({ lastResult, method: "GET" });

  return (
    <FormProvider context={form.context}>
      <MyForm>
        <MyInput name={fields.query.name} />
      </MyForm>
    </FormProvider>
  );
}

I'd think this, plus an easy way to check if value !== initialValue at the field level, could help make it easy to build validated GET forms and progressively enhanced self-submitting uncontrolled inputs.

[edmundhung]

Totally agree we should give GET forms more love and better support overall.

That said, Conform doesn’t auto-reset the form when you change defaultValue, because it’s super common to inline that default:

useForm({
  // This object reference is brand-new on every render:
  defaultValue: { name: '' },
})

If we tried resetting on every change, we would have to run a deep-equality check, and even then it might fire at the worst possible moment, nuking whatever someone's typing. Without a straightforward opt-in/opt-out, that could lead to a really frustrating UX.

The last result idea is interesting, but I couldn't quite figure out a way to tell whether "this is the new default I actually want" from "this is just the last submission". Imagine auto-submitting on every keystroke: by the time you get the response, the user might have already moved on. We can't overwrite their new input with stale data in such case.

I'm not opposed to offering a reset-on-default-change feature, but I'm not quite sure yet whether it should be the default.

[edmundhung]

plus an easy way to check if value !== initialValue at the field level

If you are referring to field level dirty flag, would something like this work?

const isEmailDirty = useFormData(
  formRef,
  (formData) => formData.get('email') !== getValueAtPath(defaultValue, 'email'),
);

Conform has a set of utilities to work with path and I have been thinking about exporting those.

[edmundhung]

How about keeping the concept of key, but default it to a json serialised version of the default value? That way conform will reset the form when default value changes by default, and you can override the behaviour by providing a custom key.

[brunobely]

Any plans for adding per-field validation, especially async validation? For instance, checking if a username is available while typing out the form. With TanStack Form's async validation), I'm able to show a loader on the field while it's validating (the validator is just a Server Action) and then a checkmark if it's successful (still trying to figure out how to do this part with Conform).

But the best part about per-field async validation is that it's super easy to write shared code that sets up entire forms without having to create schemas differently depending on whether or not I'm using async validation.

[edmundhung]

There will be several ways to do async validation. I am just writing the introductory post right now. It should be published in a day or two.