Using checkboxes with zod is confusing

[fiws]

Using checkboxes with zod is confusing

[edmundhung]

Definitely agree that the type coercion behaviour should be documented. Would you be interested in contributing? I think we can have a dedicated guide about type coercion.

FYI, to set a default value with zod, you should use .transform(v => v ?? false). .refine() is meant for validation and Invalid input is the default error message.

With regards to the behaviour, what you found is pretty much correct. This is mainly because FormData express everything in the form of value. There is no false in the FormData and all we know is if an entry with a specific name and value exists. The server cannot tell whether the checkbox is unchecked or if it is never rendered in the form. Conform also make an additional assumption that you haven't customize the checkbox value. As it considers the result true only when the value is on (The default value of checkbox / radio button).

I am happy to adjust the behaviour if we believe there is a better approach. Here is a few concerns I had if we default the value to false:

• We need to use .refine() to mark a checkbox as required (e.g. z.boolean().refine(value => value, 'Required'))
• There is no different with z.boolean().optional() anymore as there will always be a value.
• Zod has a feature called errorMap which you can map both standard and custom error using a specific code. After this change, boolean no longer works with the standard required code as it is now a custom validation (i.e. .refine())

[fiws]

My bad with the refine/transform. I think more/better documentation is the way to go here. Having even more special behaviour makes things more unpredictable.

Maybe this could just be a short chapter somewhere? Something like the following:

---

Working with checkboxes

Checkboxes only have an "on" state. Leaving them unchecked will result in the browser not sending any value for that field.
To work around this, you can adjust your zod schema based on the prefered outcome:

• z.boolean() – Checkbox is required. Leaving it unchecked results in a validation error
• z.boolean().optional() – Checkbox is not required. Leaving it unchecked results in undefined
• z.boolean().default(false) – Checkbox is not required. Leaving it unchecked results in false.

[fiws]

Actually forgot about default: z.boolean().default(false) that should be the cleanest solution for my problem.

[sweeperq]

Actually forgot about default: z.boolean().default(false) that should be the cleanest solution for my problem.

I don't know what the deal is, but this doesn't work for me. When it is unchecked it indeed defaults to false. But when it is checked I get Expected boolean, received string. The only way I can get checkboxes to consistently work correctly is z.preprocess((x) => x === "on", z.boolean())

[edmundhung]

I don't know what the deal is, but this doesn't work for me. When it is unchecked it indeed defaults to false. But when it is checked I get Expected boolean, received string. The only way I can get checkboxes to consistently work correctly is z.preprocess((x) => x === "on", z.boolean())

There is a test dedicated for this. So I would expect it to work. It could be a regression on zod 3.22. Maybe try downgrading your zod version to 3.21.4 and see if the issue is resolved.