useForm
A custom React hook for form state management and validation
useForm is a lightweight typed form state manager built around Standard Schema validation. It keeps field values in a ref, exposes a render-prop Field, and coordinates validation, submission, reset, and pending state.
Unlike the Form Builder library, this hook is intentionally small and React-oriented. It is a good fit for regular DOM forms where you want schema validation without introducing a larger form abstraction.
Installation
CLI
npx shadcn add https://ui.tiesen.id.vn/r/use-form.jsonManual
Copy and paste the following code into your project.
// oxlint-disable max-statementsimport * as React from 'react'interface FormError { message: string | null issues?: StandardSchemaV1.Issue[]}type OnChangeParam<TValue> = | React.ChangeEvent< HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement > | TValueinterface FormFieldProps<TName extends keyof TValues, TValues> { name: TName render: (props: { field: { id: string name: TName value: TValues[TName] onChange: (params: OnChangeParam<TValues[TName]>) => void onBlur: () => void // Accessibility attributes form: string 'aria-describedby': string 'aria-invalid': boolean } meta: { descriptionId: string errorId: string errors: StandardSchemaV1.Issue[] isPending: boolean } }) => React.ReactNode}function extractError(errors: StandardSchemaV1.Issue[], name: string) { return errors.filter((issue) => { if (!issue.path || issue.path.length === 0) return false const [firstPath] = issue.path if (typeof firstPath === 'object' && 'key' in firstPath) return firstPath.key === name return firstPath === name })}export function useForm< TValues, TData, TError extends FormError, TSchema extends | StandardSchemaV1 | ((values: TValues) => TResults | Promise<TResults>), TResults extends StandardSchemaV1.Result<TValues>,>(props: { defaultValues: TValues schema?: TSchema onSubmit: (data: TValues) => TData | Promise<TData> onSuccess?: (data: TData) => unknown | Promise<unknown> onError?: (error: TError) => unknown | Promise<unknown>}): { formId: string Field: <TName extends keyof TValues>( props: FormFieldProps<TName, TValues> ) => React.ReactNode handleSubmit: (event?: React.SubmitEvent) => void state: { values: TValues data: TData | null error: TError | null isPending: boolean } reset: () => void} { const { defaultValues, schema, onSubmit, onSuccess, onError } = props const formId = React.useId() const formValuesRef = React.useRef<TValues>(defaultValues) const formDataRef = React.useRef<TData | null>(null) const formErrorRef = React.useRef<TError | null>(null) const [isPending, startTransition] = React.useTransition() const setFormValue = React.useCallback( <TKey extends keyof TValues>(field: TKey, value: TValues[TKey]) => { formValuesRef.current = { ...formValuesRef.current, [field]: value } }, [] ) const validate = React.useCallback( async (values: TValues): Promise<TValues> => { if (!schema) return values const result = '~standard' in schema ? await schema['~standard'].validate(values) : await schema(values) if ('issues' in result) throw result.issues return (result.value ?? result) as TValues }, [schema] ) const handleSubmit = React.useCallback( (event?: React.SubmitEvent) => { if (event) { event.preventDefault() event.stopPropagation() } formDataRef.current = null formErrorRef.current = null startTransition(async () => { try { const validValues = await validate(formValuesRef.current) formValuesRef.current = validValues const result = await onSubmit(validValues) formDataRef.current = result ?? null await onSuccess?.(result) } catch (error) { let issues: FormError['issues'] if (Array.isArray(error)) issues = error let message = 'Validate failed' if (error instanceof Error) ({ message } = error) formErrorRef.current = { message, issues } as TError await onError?.(formErrorRef.current) } }) }, [onSubmit, onSuccess, onError, validate] ) const Field = React.useCallback( function FormField<TName extends keyof TValues>({ name, render, }: FormFieldProps<TName, TValues>) { const id = React.useId() const [value, setValue] = React.useState( () => formValuesRef.current[name] ) const prevValueRef = React.useRef(value) const [errors, setErrors] = React.useState<StandardSchemaV1.Issue[]>(() => extractError(formErrorRef.current?.issues ?? [], name as string) ) const onChange = React.useCallback( (param: OnChangeParam<TValues[TName]>) => { if (param === null) return setErrors([]) let newValue if (typeof param === 'object' && 'target' in param) { const target = param.target as HTMLInputElement if (target.type === 'checkbox') newValue = target.checked else if (target.type === 'number') newValue = Number.isNaN(target.valueAsNumber) ? 0 : target.valueAsNumber else newValue = target.value } else newValue = param as TValues[TName] setValue(newValue as TValues[TName]) setFormValue(name, newValue as TValues[TName]) }, [name] ) const onBlur = React.useCallback(async () => { if (prevValueRef.current === value) return prevValueRef.current = value try { const result = await validate({ ...formValuesRef.current, [name]: value, }) setFormValue(name, result[name]) } catch (error) { if (!Array.isArray(error)) return setErrors(extractError(error, name as string)) } }, [name, value]) const meta = React.useMemo( () => ({ descriptionId: `form-${formId}-field-${id}-description`, errorId: `form-${formId}-field-${id}-error`, errors, isPending, }), [id, errors] ) return render({ field: { id: `form-${formId}-field-${id}`, name, value, onChange, onBlur, form: `form-${formId}`, 'aria-describedby': meta.errors.length > 0 ? `${meta.descriptionId} ${meta.errorId}` : meta.descriptionId, 'aria-invalid': meta.errors.length > 0, }, meta, }) }, [formId, setFormValue, validate, isPending] ) const reset = React.useCallback( () => startTransition(() => { formValuesRef.current = defaultValues formDataRef.current = null formErrorRef.current = null }), [defaultValues] ) return React.useMemo( () => ({ formId: `form-${formId}`, Field, handleSubmit, state: { get values() { return formValuesRef.current }, get data() { return formDataRef.current }, get error() { return formErrorRef.current }, get isPending() { return isPending }, }, reset, }), [formId, Field, handleSubmit, isPending, reset] )}/** The Standard Schema interface. */interface StandardSchemaV1<Input = unknown, Output = Input> { /** The Standard Schema properties. */ readonly '~standard': StandardSchemaV1.Props<Input, Output>}// oxlint-disable-next-line typescript/no-namespacedeclare namespace StandardSchemaV1 { /** The Standard Schema properties interface. */ export interface Props<Input = unknown, Output = Input> { /** The version number of the standard. */ readonly version: 1 /** The vendor name of the schema library. */ readonly vendor: string /** Validates unknown input values. */ readonly validate: ( value: unknown, options?: StandardSchemaV1.Options | undefined ) => Result<Output> | Promise<Result<Output>> /** Inferred types associated with the schema. */ readonly types?: Types<Input, Output> | undefined } /** The result interface of the validate function. */ export type Result<Output> = SuccessResult<Output> | FailureResult /** The result interface if validation succeeds. */ export interface SuccessResult<Output> { /** The typed output value. */ readonly value: Output /** A falsy value for `issues` indicates success. */ readonly issues?: undefined } export interface Options { /** Explicit support for additional vendor-specific parameters, if needed. */ readonly libraryOptions?: Record<string, unknown> | undefined } /** The result interface if validation fails. */ export interface FailureResult { /** The issues of failed validation. */ readonly issues: readonly Issue[] } /** The issue interface of the failure output. */ export interface Issue { /** The error message of the issue. */ readonly message: string /** The path of the issue, if any. */ readonly path?: readonly (PropertyKey | PathSegment)[] | undefined } /** The path segment interface of the issue. */ export interface PathSegment { /** The key representing a path segment. */ readonly key: PropertyKey } /** The Standard Schema types interface. */ export interface Types<Input = unknown, Output = Input> { /** The input type of the schema. */ readonly input: Input /** The output type of the schema. */ readonly output: Output } /** Infers the input type of a Standard Schema. */ export type InferInput<Schema extends StandardSchemaV1> = NonNullable< Schema['~standard']['types'] >['input'] /** Infers the output type of a Standard Schema. */ export type InferOutput<Schema extends StandardSchemaV1> = NonNullable< Schema['~standard']['types'] >['output']}Usage
import { useForm } from '@/hooks/use-form'
import * as z from 'zod'
const schema = z.object({
email: z.string().email(),
})
export function LoginForm() {
const form = useForm({
defaultValues: { email: '' },
schema,
onSubmit: async (values) => {
console.log(values)
},
})
return (
<form onSubmit={form.handleSubmit}>
<form.Field
name='email'
render={({ field, meta }) => (
<>
<label htmlFor={field.id}>Email</label>
<input {...field} />
{meta.errors.map((error, index) => (
<p key={index}>{error.message}</p>
))}
</>
)}
/>
<button type='submit' disabled={form.state.isPending}>
Submit
</button>
</form>
)
}Validation
The schema option accepts either a Standard Schema implementation or a function returning a Standard Schema result.
Validation runs:
- before
onSubmit, - when a field loses focus after its value changed.
Field errors are filtered by the field name from the issue path.
Field rendering
The render callback receives field and meta:
{
field: {
id: string
name: TName
value: TValues[TName]
onChange: (valueOrEvent) => void
onBlur: () => void
form: string
'aria-describedby': string
'aria-invalid': boolean
},
meta: {
descriptionId: string
errorId: string
errors: StandardSchemaV1.Issue[]
isPending: boolean
}
}When passed a DOM change event, onChange maps checkboxes to booleans, number inputs to numbers, and other inputs to their string value.
Submission lifecycle
handleSubmit prevents the browser default, validates the current values, invokes onSubmit, and then calls either onSuccess or onError.
The returned state exposes the latest form values, result data, error, and transition state.
Reset
form.reset()Reset restores the original defaultValues and clears stored result/error state.
API Reference
useForm
useForm<TValues, TData, TError, TSchema, TResults>(options)| Option | Description |
|---|---|
defaultValues | Initial typed form values. |
schema | Standard Schema or validation function. |
onSubmit | Callback receiving validated values. May return a value or Promise. |
onSuccess | Optional callback for successful submission. |
onError | Optional callback for validation/submission failures. |
Returns:
| Property | Description |
|---|---|
formId | Stable form identifier used by generated accessibility IDs. |
Field | Generic field render-prop component. |
handleSubmit | Submit handler for the native form element. |
state.values | Current form values. |
state.data | Last successful submission result. |
state.error | Last form error. |
state.isPending | React transition pending state. |
reset | Restores defaultValues and clears result/error state. |