zod-form-data v2.0.2

zod-form-data

Validation helpers for zod specifically for parsing FormData or URLSearchParams. This is particularly useful when using Remix and combos well with remix-validated-form.

The main goal of this library is deal with the pain point that everything in FormData is a string. Sometimes, properly validating this kind of data requires a lot of extra hoop jumping and preprocessing. With the helpers in zod-form-data, you can write your types closer to how you want to.

Example

import { zfd } from "zod-form-data";

const schema = zfd.formData({
  name: zfd.text(),
  age: zfd.numeric(z.number().min(25).max(50)),
  likesPizza: zfd.checkbox(),
});

// This example is using Remix, but it will work
// with any `FormData` or `URLSearchParams` no matter where you get it from.
export const action = async ({ request }) => {
  const { name, age, likesPizza } = schema.parse(await request.formData());
  // do something with parsed data
};

Installation

npm install zod-form-data

Contributing

The eventual goal is to have a helper to preprocess and/or validate most types of native inputs. If you have a helper for an input type that isn't in this library, feel free to open a PR to add it!

API Reference

Contents

• formData
• text
• numeric
• checkbox
• file
• repeatable
• repeatableOfType

formData

This helper takes the place of the z.object at the root of your schema. It wraps your schema in a z.preprocess that extracts all the data out of a FormData and transforms it into a regular object. If the FormData contains multiple entries with the same field name, it will automatically turn that field into an array. (If you're expecting multiple values for a field, use repeatable.)

The primary use-case for this helper is to accept FormData, but it works with any iterable that returns entries. This means it can accept URLSearchParams or regular objects as well.

Usage

You can use this the same way you would use z.object.

const schema = zfd.formData({
  field1: zfd.text(),
  field2: zfd.text(),
});

const someFormData = new FormData();
const dataObject = schema.parse(someFormData);

It's also possible to pass a zod schema to formData.

const schema = zfd.formData(
  z.object({
    field1: zfd.text(),
    field2: zfd.text(),
  })
);

text

Transforms any empty strings to undefined before validating. This makes it so empty strings will fail required checks, allowing you to use optional for optional fields instead of nonempty for required fields. If you call zfd.text with no arguments, it will assume the field is a required string by default. If you want to customize the schema, you can pass that as an argument.

Usage

const const schema = zfd.formData({
  requiredString: zfd.text(),
  stringWithMinLength: zfd.text(z.string().min(10)),
  optional: zfd.text(z.string().optional()),
})

numeric

Coerces numerical strings to numbers transforms empty strings to undefined before validating. If you call zfd.number with no arguments, it will assume the field is a required number by default. If you want to customize the schema, you can pass that as an argument.

Note: The preprocessing only coerces the value into a number. It doesn't use parseInt. Something like "24px" will not be transformed and will be treated as a string.

Usage

const schema = zfd.formData({
  requiredNumber: zfd.numeric(),
  numberWithMin: zfd.numeric(z.number().min(13)),
  optional: zfd.numeric(z.number().optional()),
});

checkbox

Validates a checkbox field as a boolean. Unlike other helpers, this is not a preprocesser, but a complete schema that should do everything you need. By default, it will treat "on" as true and undefined as false, but you can customize the true value.

If you have a checkbox group and you want to leave the values as strings, repeatableField might be what you want.

Usage

const schema = zfd.formData({
  defaultCheckbox: zfd.checkbox(),
  checkboxWithValue: zfd.checkbox({ trueValue: "true" }),
  mustBeTrue: zfd.checkbox().refine((val) => val, "Please check this box"),
});

Background on native checkbox behavior

If you're used to using client-side form libraries and haven't dealt with native form behavior much, the native checkbox behavior might be non-intuitive (it was for me).

Take this checkbox:

<input name="myCheckbox" type="checkbox" />

If you check this checkbox and submit the form, the value in the FormData will be "on".

If you add a value prop:

<input name="myCheckbox" type="checkbox" value="someValue" />

Then the checked value of the checkbox will be "someValue" instead of "on".

If you leave the checkbox unchecked, the FormData will not include an entry for myCheckbox at all.

(Further reading)

file

Transforms any empty File objects to undefined before validating. This makes it so empty files will fail required checks, allowing you to use optional for optional fields. If you call zfd.file with no arguments, it will assume the field is a required file by default.

Usage

const schema = zfd.formData({
  requiredFile: zfd.file(),
  optional: zfd.file(z.instanceof(File).optional()),
});

There is a unique case in Remix when using a CustomUploadHandler, the field will be a File on the client side, but an ID string (or URL) after uploading on the server.

In this case you will need the schema to switch to string on the server:

const baseSchema = z.object({
  someOtherField: zfd.text(),
});

const clientSchema = z.formData(
  baseSchema.and({
    file: zfd.file(),
  })
);

const serverSchema = z.formData(
  baseSchema.and({
    file: z.string(),
  })
);

Note: This will return File | string for the type. TODO: Example of type safety for this

repeatable

Preprocesses a field where you expect multiple values could be present for the same field name and transforms the value of that field to always be an array. This is specifically meant to work with data transformed by zfd.formData (or by remix-validated-form).

If you don't provide a schema, it will assume the field is an array of zfd.text fields. If you want to customize the type of the item, but don't care about validations on the array itself, you can use repeatableOfType.

Usage

const schema = zfd.formData({
  myCheckboxGroup: zfd.repeatable(),
  atLeastOneItem: zfd.repeatable(z.array(zfd.text()).min(1)),
});

repeatableOfType

A convenience wrapper for repeatable. Instead of passing the schema for an entire array, you pass in the schema for the item type.

Usage

const schema = zfd.formData({
  repeatableNumberField: zfd.repeatableOfType(zfd.numeric()),
});