Handle stringified JSON for Future API.

[lhapaipai]

Hi developers!

I noticed the very interesting customize option for coerceFormValue but I encounter some unexpected results when I try to use it in my application.

Context

I have a file Picker field and I want to use it in a MediaField component. I simulate the file picker with a simple <button> that calls control.change when we click on it.

I encounter two issues:

1. I need to prepare data for the useForm defaultValue option
2. As the data is a stringified object, I encounter a TypeScript type error

Reproduction

import { coerceFormValue, formatResult } from "@conform-to/zod/v4/future";
import {
  FieldName,
  FormProvider,
  isDirty,
  parseSubmission,
  report,
  useControl,
  useField,
  useForm,
  useFormData,
} from "@conform-to/react/future";
import { z } from "zod/v4";
import { data, Form } from "react-router";

const mediaSchema = z.object({
  id: z.number(),
  src: z.string(),
  width: z.number(),
  height: z.number(),
});
type Media = z.infer<typeof mediaSchema>;

const schema = coerceFormValue(
  z.object({
    media: mediaSchema,
  }),
  {
    customize(type) {
      if (type === mediaSchema) {
        return (value) => {
          if (typeof value !== "string") {
            return value;
          }
          return JSON.parse(value);
        };
      }
      return null;
    },
  },
);

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

  if (!result.success) {
    return report(submission, {
      error: formatResult(result),
    });
  }

  console.log("update server side", result.data);
  return data(null);
}

export async function loader() {
  const infos = {
    media: {
      id: 123,
      src: "/abc.jpg",
      width: 800,
      height: 800,
    },
  };
  return { infos };
}

function MediaField({ name }: { name: FieldName<Media> }) {
  const field = useField(name);
  const control = useControl({
    defaultValue: field.defaultValue,
  });

  function handleChange() {
    control.change(
      JSON.stringify({
        id: Math.floor(Math.random() * 1000),
        src: "/abc.jpg",
        width: 800,
        height: 800,
      }),
    );
  }

  return (
    <>
      <input type="text" ref={control.register} name={field.name} />
      <div>value: {control.value}</div>
      <button type="button" onClick={handleChange}>
        set new media
      </button>
    </>
  );
}

export default function Component({ loaderData, actionData }) {
  const { infos } = loaderData;

  // Issue 1: Need to prepare data by stringifying
  const prepared = {
    media: JSON.stringify(infos.media),
  };

  const { form, fields } = useForm(schema, {
    id: "form-zod",
    defaultValue: prepared, // Issue 2: TypeScript error here
    lastResult: actionData,
  });

  const dirty = useFormData(form.id, (formData) => {
    return isDirty(formData, { defaultValue: prepared });
  });

  return (
    <FormProvider context={form.context}>
      <div>Dirty {dirty ? "yes" : "no"}</div>
      <Form method="post" {...form.props}>
        <MediaField name={fields.media.name} />
        <div>errors: {fields.media.errors}</div>
        <div>
          <button>Save</button>
        </div>
      </Form>
    </FormProvider>
  );
}

Issues

Issue 1: Data preparation required

I need to manually prepare the data from the loader by stringifying the object:

const prepared = {
  media: JSON.stringify(infos.media),
};

Without this preparation, the form doesn't work correctly even though I've set up the customize function to handle JSON parsing.

Issue 2: TypeScript type error

When using the prepared data as defaultValue, I get a TypeScript error because:

• The schema expects media to be of type Media (object)
• But I'm passing a stringified version (string)

const { form, fields } = useForm(schema, {
  defaultValue: prepared, // Type error: string is not assignable to Media
});

Question

Is there a better way to handle stringified JSON values with the customize option? I expected that:

1. The customize function would allow me to pass the original object (not stringified) as defaultValue
2. TypeScript would understand that stringified values are valid for fields with custom coercion

Expected behavior: Being able to pass the original object structure from the loader directly to defaultValue, and having the customize function handle the stringification internally when needed.

Current behavior: I need to manually stringify the data AND deal with TypeScript type mismatches.

Am I using the customize option incorrectly, or is this the intended pattern?

Idea

Related to this example and to this discussion : #1135

I'm wondering if a prepareFromZodSchema utilitary function could be interesting ?

import { z } from "zod/v4";
// hypothetical ?
import { prepareFromZodSchema } from "@conform-to/zod/v4/future";

const mediaSchema = z.object({
  id: z.number(),
  src: z.string(),
  width: z.number(),
  height: z.number(),
});
const dateTimeLocalSchema = z.date();

type Media = z.infer<typeof mediaSchema>;

const formSchema = z.object({
  media: mediaSchema,
  createdAt: dateTimeLocalSchema
})

const schema = coerceFormValue(
  formSchema,
  {
    customize(type) {
      if (type === mediaSchema) {
        return (value) => {
          if (typeof value !== "string") {
            return value;
          }
          return JSON.parse(value);
        };
      }
      return null;
    },
  },
);


const value = {
  media: {
    id: 123,
    src: "abc.jpg",
    width: 800,
    height: 800
  },
  createdAt: new Date("2026-01-01T12:00:00"),
};

const preparedValue = prepareFromZodSchema(value, formSchema, {
  customize(type) {
    if (type === mediaSchema) {
      return (value) => {
        if (typeof value === "string") {
          return value;
        }
        return JSON.stringify(value);
      };
    } else if (type === dateTimeLocalSchema) {
      return (value) => {
        if (typeof value === "string") {
          return value.substring(0, 16)
        } else if (value instanceof Date) {
          return value.toISOString().substring(0, 16)
        }
        return value
      }
    }
    return null;
  },
})

preparedValue === {
  media: `{id:123,src:"abc.jpg",width:800,height:800}`,
  createdAt: "2026-01-01T12:00"
}

Thanks for your help!

[edmundhung]

Hi,

For issue 1, customize only handles coercion (deserialisation), so it does not have enough information to decide how the data should be serialised. I do understand the pain of having to do this manually though. What you are probably looking for is a schema-based serializer and deserializer. That is not impossible, but it would require fairly extensive schema introspection, and it is hard to support every kind of schema consistently. It is definitely worth exploring, but it would take a non-trivial amount of effort.

A simpler alternative could be to extend Conform’s naming conventions to support automatic JSON serialisation, for example:

<input
  name={fields.foo.nameForJSON}
  defaultValue={fields.foo.defaultJSON}
/>

We could then extend useControl to accept more complex data structures and serialise them as JSON when it detects a name pattern that expects JSON. The downside is that this pushes more setup and responsibility onto the developer.

For issue 2, I agree this looks like a bug. It should accept a string as-is for this use case.

[lhapaipai]

Hi @edmundhung, I effectively tried to implement a schema-based serializer, and it turned into a typing nightmare, even though I was working with non-generic schemas.

type IsMediaSchema<S> = S extends typeof mediaSchema ? true : false;

export type UnwrapZodType<T extends $ZodType> =
  T extends $ZodDefault<infer U>
    ? // @ts-ignore
      UnwrapZodType<U>
    : T extends $ZodNullable<infer U>
      ? // @ts-ignore
        UnwrapZodType<U>
      : T extends $ZodOptional<infer U>
        ? // @ts-ignore
          UnwrapZodType<U>
        : T extends $ZodCatch<infer U>
          ? // @ts-ignore
            UnwrapZodType<U>
          : T;

export type PrepareWithZodResult<S extends $ZodObject> = {
  // @ts-ignore
  [K in keyof output<S>]: UnwrapZodType<S["_zod"]["def"]["shape"][K]> extends $ZodDate
    ? string
    : // @ts-ignore
      S["_zod"]["def"]["shape"][K] extends $ZodArray<infer U>
      ? U extends $ZodObject
        ? RecursePrettify<PrepareWithZodResult<U>[]>
        : output<U>[]
      : // @ts-ignore
        UnwrapZodType<S["_zod"]["def"]["shape"][K]> extends $ZodObject
        ? // @ts-ignore
          IsMediaSchema<UnwrapZodType<S["_zod"]["def"]["shape"][K]>> extends true
          ? string | null
          : // @ts-ignore
            Prettify<PrepareWithZodResult<UnwrapZodType<S["_zod"]["def"]["shape"][K]>>>
        : output<S>[K];
};

Unfortunately, I don’t have enough in-depth TypeScript knowledge to propose something truly robust here.

Honestly, I find the alternative using nameForJSON and defaultJSON much simpler. While it may be less elegant, it has the advantage of being significantly easier to maintain...

[lhapaipai]

resolved with #1180