Unhappy experience with checkboxes

[MartinCura]

@tanstack/react-form: ^v1.14.0

Hi there, digging the library! and i've been slowly using it in place of RHF, but i feel it still has some warts, at least when, like me, it's used alongside Next.js Server Actions and Zod. Hopefully it's something i'm doing wrong and it can be better documented.

In this case the problem is with doing checkboxes right. I want:

• An <input type="checkbox" ...>
• Default value based on existing value and false as fallback
• Client-side validation using Zod schema, with an onBlur form-level validator
• On submit i send a FormData (i like progessive enhancement and i like useActionState)
• An action which also validates/parses the input

Here's a quickly put together extract from my current working code, the best i could achieve after some hours:

// schemas.ts
export const schema = z.object({
  // Note: allows for receiving "on"/"off" and transforms to boolean
  enabled: z.stringbool().default(false),
})

export const formOpts = formOptions({
  validators: {
    onBlur: schema,
  },
  defaultValues: {
    enabled: "off" as string | undefined,
  } as { enabled?: string | undefined },
})

type Thing = {
  enabled: boolean
}

// component.tsx
export const MyForm({ thing }: { Thing }) {
  const formRef = useRef<HTMLFormElement>(null)

  const [isPendingTransition, startTransition] = useTransition()
  const [formState, formAction, isPendingAction] = useActionState(action, initialFormState)
  const isPending = isPendingTransition || isPendingAction

  const form = useAppForm({
    ...formOpts,
    transform: useTransform((baseForm) => mergeForm(baseForm, formState ?? {}), [formState]),
    defaultValues: {
      ...formOpts.defaultValues,
      enabled: thing.enabled ? "on" : "off",
    } as Omit<z.input<typeof schema>, "enabled"> & { enabled?: string | undefined },
    onSubmit: () => {
      startTransition(() => formAction(new FormData(formRef.current!)))
    },
  }

  return (
    <form.AppForm>
      <form.Form ref={formRef} action={formAction}>
        <form.AppField name="enabled">
          {(field) => (
            // (Based on shadcn's)
            <Switch
              name={field.name}
              checked={field.state.value === "on"}
              onCheckedChange={() => field.handleChange(field.state.value !== "on" ? "on" : "off")}
              onBlur={field.handleBlur}
              {...props}
            />
        </form.AppField>
      </form.Form>
    </form.AppForm>
  )
}

// actions.ts
const serverValidate = createServerValidate({
  ...formOpts,
  onServerValidate: schema,
})

export async function action(_prevState: unknown, formData: FormData) {
  try {
    const inputs = schema.parse(await serverValidate(formData))
    console.log("inputs", inputs)
  } catch (err) {
    if (!(err instanceof ServerValidateError)) {
      console.error("Unexpected error")
      throw err
    }
    console.warn("err", err)
    return err.formState
  }
}

As you can see i ended up having to deal with enabled as a string. Fine, ideally i'd love for the value to be a boolean but that i couldn't make it work.

My experience doing this with RHF wasn't happy either but i ended up making it work, kind of creating 2 types: one for input and one for output (sometimes using z.preprocess() and zod-form-data's zfd.checkbox()).

The problems here are ergonomic but also type-based. If for example i didn't make that type assertion on the default value then it complains because Zod (4) is allowing a "key optional" enabled?: string | undefined while in defaultValue it's just string | undefined and that for some reason is a problem. As a related aside, i'm sure that something better can be done for DX if a standard schema validator is passed so that i don't have to have to be doing stuff like name: "" as string | null.

The types of 'validators.onBlur' are incompatible between these types.
// (...Several TS error lines removed...)
Property 'enabled' is optional in type '{ enabled?: string | undefined; }' but required in type '{ enabled: string | undefined; }'.  ts(2345)

As a related aside, i'm sure that something better can be done for DX if a standard schema validator is passed so that i don't have to have to be doing stuff like name: "" as string | null.

Among other things, the server validator just validating but not parsing means i still have to use my schema in the server action, and thus the validation is done twice, where the validator just helps with decoding the FormData (for which elsewhere i use zfd or decode-formdata, and iirc you guys and gals use something like it too). The zod parsing also removes extraneous keys like $ACTION_REF_1.

---

To keep complaints short, here's what a much happier experience would look like for me:

// schemas.ts
export const schema = z.object({
  enabled: z.stringbool().default(false),
})

export const formOpts = formOptions({
  validators: {
    onBlur: schema,
  },
  defaultValues: {
    // simpler, and i'm happy if i don't have to do type assertions to widen the type
    enabled: false,
  },
})

type Thing = {
  enabled: boolean
}

export const MyForm({ thing }: { Thing }) {
  const formRef = useRef<HTMLFormElement>(null)

  const [isPendingTransition, startTransition] = useTransition()
  const [formState, formAction, isPendingAction] = useActionState(action, initialFormState)
  const isPending = isPendingTransition || isPendingAction

  const form = useAppForm({
    ...formOpts,
    transform: useTransform((baseForm) => mergeForm(baseForm, formState ?? {}), [formState]),
    defaultValues: {
      ...formOpts.defaultValues,
      enabled: thing.enabled,
    },
    onSubmit: () => {
      // would also love to not have to do this in each form but that's a different discussion entirely
      startTransition(() => formAction(new FormData(formRef.current!)))
    },
  }

  return (
    <form.AppForm>
      <form.Form ref={formRef} action={formAction}>
        <form.AppField name="enabled">
          {(field) => (
            <Switch
              name={field.name}
              checked={field.state.value === "on"}
              onCheckedChange={() => field.handleChange(field.state.value !== "on" ? "on" : "off")}
              // checked={field.state.value}
              // onCheckedChange={field.handleChange}
              // or onCheckedChange={() => field.handleChange(!field.state.value)}
              onBlur={field.handleBlur}
              {...props}
            />
        </form.AppField>
      </form.Form>
    </form.AppForm>
  )
}

// actions.ts
const serverParse = createServerParse({
  ...formOpts,
  // or maybe if the formOpts could receive this directly it could help somehow in making everything simpler? i'm sure it goes against other use cases
  schema,
})

export async function action(_prevState: unknown, formData: FormData) {
  try {
    const inputs = await serverParse(formData)
    console.log("inputs", inputs)
    //                    ^ inputs.enabled is boolean
  } catch (err) {
    if (!(err instanceof ServerValidateError)) {
      console.error("Unexpected error")
      throw err
    }
    console.warn("err", err)
    return err.formState
  }
}

---

So, sorry for the big post 😅 I'm just struggling with some use cases which i don't consider atypical at all. In some sense it's obviously caused by having to reconcile (client-heavy form libs) with (non-symmetric schemas) with (native HTML form inputs that have annoying behaviors) with (React/Next.js Server Actions).

I'm open to being told i'm holding it wrong! And thank you!

[LeCarbonator]

As a related aside, i'm sure that something better can be done for DX if a standard schema validator is passed so that i don't have to have to be doing stuff like name: "" as string | null.

Yes, standard schemas are a bit iffy with defaultValues. Notably, you need to inform typescript that your defaultValues aren't just an object, but a z.input<typeof yourSchema>. The type safe way to do it is to extract the defaultValues:

const defaultValues: z.input<typeof yourSchema> = { /* ... */ }

However, as you probably noticed too, it has a hard time combining with formOpts since it would need some workaround like this:

const defaultValues: z.input<typeof formOpts.validators.onChange> = { /* ... */ }

There's multiple issues and feature requests that address how standard schemas should interact. Some devs prefer standard schemas to be a partial of their defaultValues, others want the defaultValues to be a partial of the schemas ...
As it is right now, standard schemas simply have an input and output type, and defaultValues should match the input type created from whatever schema library you use.

There's likely a solution that can be good for everyone.
For now, my suggestion is this (for dynamic defaultValues like your case):

// schemas.ts
export const schema = z.object({
  enabled: z.stringbool().default(false),
})

export const formOpts = formOptions({
  validators: {
    onBlur: schema,
  },
  defaultValues: {
    // simpler, and i'm happy if i don't have to do type assertions to widen the type
    enabled: false,
  },
})

type Thing = {
  enabled: boolean
}

export function getEmptyFormValues(params: Thing): z.input<typeof schema> {
   return {
      // manage conversions here. 
   }
}

// form.tsx
const form = useForm({
   ...formOpts,
   defaultValues: getEmptyFormValues(params)
})

[MartinCura]

Thank you for your answer.

Yes, i'm sure there's lots of opinions about this already, hope mine helps in some way. I haven't thought about this in the more general case but surely there's also conflict between input and output types, in how defaultValues and the schemas relate, etc. In some way i'd love to just tell the form: "here's what you're parsing/validating with, use it's input shape as the shape of the form fields". of course i'm surely missing more complex stuff

I tried what you said and it helps for the form (basically instead of doing a type assertion i widen the defaultValues type by deciding it as return type of the function, right?).

But i still get a type error when declaring serverValidate:

Property 'enabled' is optional in type '{ enabled?: string | undefined; }' but required in type '{ enabled: string | undefined; }'.

Again, not the end of the world and i solve it with an as ..., but if i can be of help in understanding use cases, i'm here.

As an aside: you mentioning standard-schema specifically... if i explicitly tell the library i'm passing a Zod schema instead of an abstract standard-schema, does it help in any way?

[LeCarbonator]

As an aside: you mentioning standard-schema specifically... if i explicitly tell the library i'm passing a Zod schema instead of an abstract standard-schema, does it help in any way?

Standard Schema was created by a collaboration that involved the zod developer. It's a common interface so that you can support any validation library that implements it instead of requiring an adapter for every single one. The schema repository lists common validation libraries that support it.

When it comes to zod, you have some options. From what I heard, zod allows you to view the shape of a schema, which means if you know you will always have default values (strings are empty, numbers are 0 etc.), you can create a helper function that accepts a schema and outputs a valid default object.

But i still get a type error when declaring serverValidate:

It's difficult to tell without a reproducible example, but here's two likely candidates:

1. Zod does not differentiate between foo?: string and foo: string | undefined even though they mean different things in TypeScript. It may be an error resolving an optional property. Does nullable fix the issue?

2. If as ... fixes it, it is likely an issue caused by TypeScript and how it handles constant objects. You can read up on it here. The only workaround I know of for that (that is type safe) is satisfies ... as ... which is both wordy and irritating. With TypeScript having multiple keywords for generics, it may be possible to reduce the cases where that happens. We'll keep it in mind!

[MartinCura]

I'm leaving for vacation today but the reproducible example could be built with the code i put in my first message above (the "current").

1. Yes, and in Zod 4 beta Colin had added a way of distinguishing that with z.interface({ "enabled?": ... }) but for the stable release he removed it. I didn't see any mention of something like it in the docs.
2. Thanks!