Skip to main content

react/src

Runtime React renderer for Zod v4 form schemas — wraps react-hook-form with a schema walker that maps Zod types to form components.

Provides the <ZodForm> component and useZodForm() hook for dynamically rendering forms from a z.object() schema at runtime — no codegen required. Use this package when you need schema-driven forms that adapt to runtime schema changes.

Key exports:

  • ZodForm — the top-level form component; wraps RHF FormProvider
  • useZodForm — hook that calls walkSchema and wires up RHF for you
  • normalizeFormValues — call before schema.safeParse() to convert HTML empty strings
  • defaultComponentMap — the built-in HTML component set
  • shadcnComponentMap — the shadcn/ui component set
  • wrapWithSchemaLite — wrap a submit handler with the lite schema for optimized validation

Remarks​

Choose your abstraction level: <ZodForm> for zero-config, useZodForm for custom rendering, manual walkSchema for full control. Each step down trades convenience for flexibility.

Use When​

  • You need runtime schema-driven forms with dynamic schema changes — no rebuild needed when the schema updates
  • You are prototyping and don't want a codegen step — <ZodForm> renders immediately from any z.object()
  • Your schema is determined at runtime (e.g. from a backend API) — the walker evaluates schemas lazily on render

Avoid When​

  • Performance is critical and you can run codegen at build time — prefer @zod-to-form/cli for static .tsx output with zero runtime overhead
  • You need SSR with no client bundle — generated static components are lighter and have no React runtime dependency on walkSchema

Pitfalls​

  • NEVER call schema.safeParse(formValues) without first calling normalizeFormValues(formValues) — HTML inputs produce empty strings for optional fields, which Zod rejects
  • NEVER use a Zod v3 schema — this package requires Zod v4's _zod.bag and z.registry() APIs

Components​

Hooks​

Optimization​

Other​

normalizeFormValues​

Re-exports normalizeFormValues

Schema Walking​

Types​