Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createFormFactory
✓ import { createFormFactory } from 'zod-form';
✗ import createFormFactory from 'zod-form';
The primary named export for initializing the form factory. It is not a default export.
Form
✓ import { createFormFactory } from 'zod-form';
const { Form } = createFormFactory({ /* ... */ });
✗ import { Form } from 'zod-form';
The `Form` component is returned by `createFormFactory`, not directly exported from the package root. It is dynamically typed based on your schema.
Field types (e.g., Form.Field, Form.Text, Form.Select)
✓ import { createFormFactory } from 'zod-form';
const { Form } = createFormFactory({ /* ... */ });
// Then use: <Form.Field name="myField" /> or <Form.Text name="myText" />
✗ import { Field } from 'zod-form';
Individual field components are accessed as properties of the `Form` object returned by `createFormFactory`, and are type-inferred from your Zod schema. [1, 4]
This quickstart demonstrates how to define a Zod schema, create a typed form factory, and render a complete, validated form using `zod-form`'s `Form` and `Field` components. It includes basic input fields, a number input with custom onChange handling for optional values, a checkbox, and error display.
import { createFormFactory } from 'zod-form';
import { z } from 'zod';
import React from 'react';
const userSchema = z.object({
name: z.string().min(1, 'Name is required').max(50),
email: z.string().email('Invalid email address'),
age: z.number().min(18, 'Must be at least 18').max(120, 'Must be at most 120').optional(),
acceptTerms: z.boolean().refine(val => val === true, 'You must accept the terms'),
});
interface UserFormData extends z.infer<typeof userSchema> {}
const { Form, Field } = createFormFactory<UserFormData>()({
schema: userSchema,
defaultValues: {
name: '',
email: '',
age: undefined,
acceptTerms: false,
},
});
function UserProfileForm() {
const onSubmit = (data: UserFormData) => {
console.log('Form submitted:', data);
alert(JSON.stringify(data, null, 2));
};
return (
<Form onSubmit={onSubmit} className="space-y-4 p-4 border rounded shadow-sm max-w-md mx-auto">
<div>
<label htmlFor="name" className="block text-sm font-medium text-gray-700">Name</label>
<Field name="name" render={({ field }) => (
<input {...field} id="name" type="text" placeholder="Your name" className="mt-1 block w-full border border-gray-300 rounded-md shadow-sm p-2" />
)} />
<Form.Error name="name" className="text-red-500 text-sm" />
</div>
<div>
<label htmlFor="email" className="block text-sm font-medium text-gray-700">Email</label>
<Field name="email" render={({ field }) => (
<input {...field} id="email" type="email" placeholder="your@example.com" className="mt-1 block w-full border border-gray-300 rounded-md shadow-sm p-2" />
)} />
<Form.Error name="email" className="text-red-500 text-sm" />
</div>
<div>
<label htmlFor="age" className="block text-sm font-medium text-gray-700">Age (Optional)</label>
<Field name="age" render={({ field }) => (
<input {...field} id="age" type="number" placeholder="Age" className="mt-1 block w-full border border-gray-300 rounded-md shadow-sm p-2" onChange={e => field.onChange(e.target.value === '' ? undefined : Number(e.target.value))} />
)} />
<Form.Error name="age" className="text-red-500 text-sm" />
</div>
<div className="flex items-center">
<Field name="acceptTerms" render={({ field }) => (
<input {...field} id="acceptTerms" type="checkbox" checked={field.value} className="h-4 w-4 text-indigo-600 border-gray-300 rounded" />
)} />
<label htmlFor="acceptTerms" className="ml-2 block text-sm text-gray-900">I accept the terms and conditions</label>
<Form.Error name="acceptTerms" className="text-red-500 text-sm ml-2" />
</div>
<Form.SubmitButton className="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500">
Submit
</Form.SubmitButton>
</Form>
);
}
export default UserProfileForm;
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'schema')
The `schema` property was not correctly provided to `createFormFactory` or is `undefined` at runtime.
fixEnsure your Zod schema is properly imported and passed as the `schema` option to `createFormFactory`.
Error: Invalid hook call. Hooks can only be called inside of the body of a function component.
This typically indicates a mismatch in React versions or a violation of React Hooks rules (e.g., calling hooks outside a functional component or conditionally). This library relies on `react-hook-form`, which uses hooks extensively. [11]
fixVerify that you have only one instance of React installed (check `npm ls react`). Ensure that `zod-form` components and hooks are only used within functional React components. Also check `react-hook-form` and `react` peer dependency versions.
TS2345: Argument of type '...' is not assignable to parameter of type 'ZodSchema<any>'.
The TypeScript type of the schema passed to `createFormFactory` (or related utilities) does not conform to `ZodSchema`, or there's a version mismatch between Zod and `@hookform/resolvers`. [12]
fixCheck your Zod schema definition for correctness. Ensure `zod` is imported as `z` and that you are using Zod methods correctly (e.g., `z.object`, `z.string`). Verify compatible versions of `zod` and `@hookform/resolvers`.
Property 'XXX' does not exist on type 'IntrinsicAttributes & ...'
You are attempting to pass an HTML attribute or prop to a `zod-form` component (or its underlying HTML element) that is not recognized by its TypeScript definition. This often happens with typos or incorrect prop usage. [12]
fixReview the specific component's expected props or the standard HTML attributes for the element being rendered. Correct any typos. If you're using `render` props, ensure the props passed to the native HTML element are valid.
Audit
Dependencies
zodrequiredPeer dependency for defining form validation schemas.
reactrequiredPeer dependency for React component rendering.
react-hook-formrequiredPeer dependency for underlying form state management and hooks.
@hookform/resolversrequiredPeer dependency to bridge Zod schemas with React Hook Form validation.