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:

Details

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:

Details

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.

[andrew-shpak]

Is conform define any way how to reduce as Record<string, string> ?
Use- case

 const submission = parseSubmission(url.searchParams);
  const result = ratingReportFilterSchema.safeParse(submission.payload);

  if (!result.success) {
    return data({
      url: null,
    });
  }
  const searchParams = new URLSearchParams(result.data as Record<string, string>).toString();

[edmundhung]

Is there any reason you need the request.url? It looks like all it matters is finding out all the entries and then run new URLSearchParams(entries).toString()

My idea would be something like this:

function createSearchParams(
  value: Record<string, unknown>,
  serialize?: (data: unknown) => string | undefined,
): URLSearchParams;

It would find out all entries by looping over the properties of the provided value and serialize it. If serialize returns undefined, you would check if it is an object or array and recursively serialize their properties. Otherwise, skip it.

[andrew-shpak]

Is there any reason you need the request.url? It looks like all it matters is finding out all the entries and then run new URLSearchParams(entries).toString()

My idea would be something like this:

function createSearchParams(
  value: Record<string, unknown>,
  serialize?: (data: unknown) => string | undefined,
): URLSearchParams;

It would find out all entries by looping over the properties of the provided value and serialize it. If serialize returns undefined, you would check if it is an object or array and recursively serialize their properties. Otherwise, skip it.

What do you think about:

/**
 * Creates a search string from a plain object or URLSearchParams.
 *
 * @param value - Object or URLSearchParams to convert
 * @param serialize - Optional serializer for complex types (e.g., JSON.stringify)
 * @returns Search string with "?" prefix or empty string if no params
 *
 * @example
 * createSearchParams({ name: "John", age: 30 });
 * // "?name=John&age=30"
 *
 * createSearchParams({ ids: [1, 2, 3], active: true });
 * // "?ids=1&ids=2&ids=3&active=true"
 *
 * createSearchParams({});
 * // ""
 *
 * @example
 * // With custom serializer for objects
 * createSearchParams(
 *   { user: { id: 1, name: "John" } },
 *   (data) => typeof data === 'object' ? JSON.stringify(data) : String(data)
 * );
 * // "?user=%7B%22id%22%3A1%2C%22name%22%3A%22John%22%7D"
 */
export function createSearchParams(value: URLSearchParams): string;
export function createSearchParams(value: Record<string, SearchParamValue>): string;
export function createSearchParams(
  value: Record<string, unknown>,
  serialize: (data: unknown) => string | undefined
): string;
export function createSearchParams(
  value: URLSearchParams | Record<string, unknown>,
  serialize?: (data: unknown) => string | undefined
): string {
  const entries: [string, string][] = [];

  const addEntry = (key: string, serialized: string | undefined) => {
    if (serialized !== undefined && serialized !== "") {
      entries.push([key, serialized]);
    }
  };

  const iterator = value instanceof URLSearchParams ? value.entries() : Object.entries(value);

  for (const [key, rawValue] of iterator) {
    if (rawValue === null || rawValue === undefined) continue;

    if (Array.isArray(rawValue)) {
      for (const item of rawValue) {
        const serialized = serialize ? serialize(item) : String(item);
        addEntry(key, serialized);
      }
    } else {
      const serialized = serialize ? serialize(rawValue) : String(rawValue);
      addEntry(key, serialized);
    }
  }

  const params = new URLSearchParams(entries);
  return params.size > 0 ? `?${params}` : "";
}

[edmundhung]

This is looking good. A few thoughts:

• Is there any reason why this helper should accept a URLSearchParams?
• Object.entries() is not enough to handle deeply nested object. You can use the flatten helper for reference on how it handles that.
• I still think returning a URLSearchParams would be a bit more flexible here as it's a standard object that people can work with easily. Making it return a string with ? concatenated means people will now have to memorize the result format of this particular API everytime: does it include ? or not?

[andrew-shpak]

• flatten

I was thinking about Url instead of string but Url need host to work. Also by default URLSearchParams does not return ? so you need to know that as well.
Maybe we should have 2 methods ?

Currently if there are some values will be ? otherwise empty string

[edmundhung]

by default URLSearchParams does not return ? so you need to know that as well.

That's fair. Let's keep it as string.

[nikolailehbrink]

Using @conform-to/react": "^1.11.0"

Will the getInputProps helper be added to @conform-to/react/future and work with the new future export?
It’s one of my favorite helpers because it removes so much boilerplate, and I’d rather not reimplement it myself.

I went through the new Next.js examples but didn’t see it being used there. I recently built a form in Astro (with React) using the new future React export and had to rely on the current getInputProps helper. It technically works, but there’s a type mismatch. I’m not sure if using the old and new exports together is even intended.

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

export default function ContactForm() {
  const { form, fields } = useForm();

  return (
    <form {...form.props} action={action}
    > 
        <Input
          {...getInputProps(fields.email, { type: "email" })}
          placeholder="john.doe@example.com"
        />
    </form>
  );
}

[edmundhung]

Hi @nikolailehbrink, they are not fully compatible with the future APIs as I plan to deprecate them soon. You can find a recent discussion with my suggestion here: #1014 (comment)

Hope this helps. Let me know if you have any questions.

[nikolailehbrink]

Hi @edmundhung! That's actually a pretty cool suggestion and solution! Thanks for the work on this amazing library! :)

[heiwen]

I like the direction of where you are going with Conform v2.

My biggest headache right now is that I can't really use Collapsibles / Accordions from ShadCN / Radix / BaseUI since they are removing the elements from the DOM when hidden.

Remix-validated-form has a mode in which it derives the form values from React state instead of the DOM itself.

(https://www.rvf-js.io/state-mode)

Anything along these lines planned?

[afoures]

you should be able to use the forceMount props on the collapsible content component -> https://www.radix-ui.com/primitives/docs/components/collapsible#content

[heiwen]

I am actually doing this, as a workaround, right now.

But:
(i) I now have to handle the open / collapsed state myself (more boilerplate)
(ii) it makes it very difficult to work with animations (I might be doing something wrong here)
(iii) has the downside of blowing-up the DOM quite a bit for larger forms

[janhesters]

Came back here to ask, how to programmatically set an error?

import { useForm } from "@conform-to/react/future";
import { coerceFormValue } from "@conform-to/zod/v4/future";
import { useState } from "react";
import { z } from "zod";

const schema = z.object({
  sources: z.array(z.url()).min(1, { message: "Add at least one URL" }),
});

export default function SourcesForm() {
  const [sources, setSources] = useState<string[]>([]);
  const [inputValue, setInputValue] = useState("");
  const [inputError, setInputError] = useState<string | null>(null); // <-- Extra state for input validation

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

  const handleAddSource = () => {
    // Validate URL before adding to array
    const result = z.url().safeParse(inputValue.trim());
    if (!result.success) {
      setInputError("Please enter a valid URL"); // <-- How to report this via conform?
      return;
    }

    setInputError(null);
    setSources((prev) => [...prev, inputValue.trim()]);
    setInputValue("");
  };

  return (
    <form {...form.props}>
      {/* URL input - NOT part of schema, just for adding to array */}
      <div>
        <label>Add URL</label>
        <input
          type="url"
          value={inputValue}
          onChange={(e) => {
            setInputValue(e.target.value);
            setInputError(null);
          }}
        />
        <button type="button" onClick={handleAddSource}>
          Add
        </button>
        {inputError && <div>{inputError}</div>}
      </div>

      {/* Hidden inputs for actual form submission */}
      {sources.map((url, i) => (
        <input key={i} type="hidden" name={fields.sources.name} value={url} />
      ))}

      {/* Display added sources */}
      <ul>
        {sources.map((url, i) => (
          <li key={i}>
            {url}
            <button type="button" onClick={() => setSources((prev) => prev.filter((_, j) => j !== i))}>
              Remove
            </button>
          </li>
        ))}
      </ul>

      {/* Schema validation error (e.g., "Add at least one URL") */}
      {fields.sources.errors && <div>{fields.sources.errors}</div>}

      <button type="submit">Submit</button>
    </form>
  );
}

Is there a way to programmatically set/report a field error client-side in the future API?

In my use case, I have a text input that validates URLs before adding them to an array field. The input itself isn't part of the schema - it's just a staging area. Currently I'm using a separate useState for the input validation error, but it would be cleaner if I could report it through conform's error system (e.g., intent.reportError({ name: "sources", error: "Invalid URL" }) or similar).

[janhesters]

@edmundhung Is there a way to do this?

[edmundhung]

Yes, we now have a way to insert an item from another input and handle the errors automatically. See https://github.com/edmundhung/conform/releases/tag/v1.17.0.

[mxp-qk]

Hello @edmundhung, thank you for the new features for v2. I have been working with the future API lately, and it is a huge improvement.

I was trying the new <PreserveBoundary> mixed with useFormData to build a multi-step edition that displays the rendered result at the same time. I have a weird error during each validation: the text input value that isn't displayed is passed as an array on the first render.

Here is a reproduction, I take a quick look at the PreserveBoundary and preserveInputs code, but I can't tell where it might come from.

[edmundhung]

Thanks! I am glad you like it.

At first when you said that I thought we might have issue with the timing the preserved inputs being removed too late, but I don't see an array for the text input value from the logs you added inside useFormData(). Can you tell me more the issue? Which browser / os are you using? is the value duplicated?

[mxp-qk]

My bad, the reproduction I set up did not return the same error I have. I'll try to update that if I can.