Interface SchemaComponentProps<T, SchemaRef, Mode>

Zod schema, JSON Schema object, or OpenAPI document.

Zod 4 types that cannot round-trip through z.toJSONSchema() (bigint, date, map, set, symbol, function, undefined, void, nan, codec) are rejected at the type level via RejectUnrepresentableZod. Runtime conversion would throw SchemaNormalisationError with kind zod-type-unrepresentable — the static rejection surfaces the same failure at compile time.

For OpenAPI / JSON Schema documents: a $ref string pointing at the sub-schema to render — e.g. "#/components/schemas/User" or "/users/post".

Named schemaRef (not ref) so the prop survives the React / preact/compat createElement boundary, which strips the reserved ref name from the vnode prop bag.

Which side of every transform / pipe / codec to render.

• "output" (default) — renderer draws the OUTPUT side of the schema. For a z.codec(z.string(), z.number(), …) chain this renders a number input. value and onChange therefore carry the OUTPUT shape, and validate runs safeEncode (the reverse direction) so user-supplied OUTPUT values are validated against the codec.
• "input" — renderer draws the INPUT side instead. For the same codec this renders a string input, value and onChange carry the INPUT shape, and validate runs safeParse (the forward direction).

The choice is propagated through normaliseSchema → normaliseZod4 → z.toJSONSchema(..., { io }) so a single source of truth drives both the rendered JSON Schema shape and the validation direction. Has no effect for plain JSON Schema or OpenAPI inputs — those advertise a single canonical shape.

Current value to render. Typed against InferSchemaValue<T, SchemaRef, Mode> so the prop tracks the schema's inferred shape for the chosen io direction.

Falls back to unknown when the schema's value type cannot be statically inferred (runtime Record<string, unknown> JSON Schemas, OpenAPI documents without a ref, etc.), so untyped call sites still compile.

Use InferredOutputValue or InferredInputValue to narrow a value declared at the call site:

const user: InferredOutputValue<typeof userSchema> = { ... };
<SchemaComponent schema={userSchema} value={user} readOnly />
Copy

Called when the value changes (editable fields). The parameter shares the same shape as SchemaComponentProps.value so a controlled component can round-trip the value through React state without re-shaping.

Falls back to unknown for schemas whose value type cannot be statically inferred — see SchemaComponentProps.value.

Run schema.safeParse() on change and surface errors via onValidationError.

Called with the ZodError when validation fails.

Called when schema normalisation or rendering fails.

Called with each diagnostic emitted during schema processing.

When true, any diagnostic becomes a thrown error.

Per-field meta overrides — nested object mirroring schema shape.

Meta overrides applied to the root schema.

Convenience: sets readOnly on all fields.

Convenience: sets writeOnly on all fields.

Convenience: sets description on the root.

Instance-scoped widgets — override context and global widgets.

Prefix used for every input id/label htmlFor in this component subtree. Defaults to a per-instance value from useId() so multiple <SchemaComponent> instances on the same page never collide. Override for deterministic ids in screenshot tests.