A minimal React useForm hook

Nov 04, 2024

react

snippet

typescript

A deep dive into building a minimal form handling solution in React that tackles async validation, race conditions, and type safety.

Lately I’ve been coding a lot of forms. Form handling in React can be complex, especially when dealing with asynchronous validation, asynchronous submission, and type safety, precisely the features the in-house solution my team is using lacks of. So, I decided to create a minimal solution that would address these pain points.

Real world usage

We are going to use a form like this as the driving example:

Our useForm hook must:

Be type safe: We want full type-safety and autocompletion.
Support asynchronous validation: We want to allow validation that might perform API calls, so it must support asynchronous validations with proper cancellation of outdated requests
Communicate its state:
- submitting/valid states: Used to enable/disable form controls as corresponding
- focused/valid inputs state: Used to control which message (error or warning) to show
Async submission: Usually submission involves API calls, so this must be supported
Developer Experience: Simple API that doesn’t compromise on functionality nor creates a bloated chunk of code.

The console output shows the sequence of events and how our form handler manages them.

The interface

Our useForm will have the following signature:

declare function useForm<T extends Record<string, unknown>>(options: FormOptions<T>): Form<T>;

The FormOptions<T> interface shows our focus on async operations. Notice the validate function receives an AbortSignal - this is crucial for handling race conditions in async validation.

// Maps input names to their corresponding error if they are not valid
export type FormErrors<T> = {
  [key in keyof T]?: string;
};

export interface FormOptions<T> {
  // Initial values is used to infer the schema of the form
  initialValues: T;

  // Used to determine if the form is "dirty"
  isEqual?: (a: T, b: T) => boolean;

  // Validation can be sync or async.
  // Also, the name of the field being validated may be passed as an option,
  // in that case, we can return a tuple to indicate we wish to merge that
  // input error with the form errors of other inputs. This allows for
  // performing single-field validations if needed (e.g.: improve performance)
  validate?: (
    values: T,
    options: { signal: AbortSignal; name?: keyof T }
  ) =>
    | FormErrors<T>
    | [FormErrors<T>]
    | Promise<FormErrors<T> | [FormErrors<T>]>;

  // The delay to wait before validating.
  // This is used to debounce the onChange event on inputs.
  validationDelay?: number;

  // Whenever an uncontrolled error occurs when calling `validate` or
  // submitting, we wish to call this callback so the parent component
  // can handle it.
  onError?: (error: unknown) => void;
}

And our Form<T> model is defined as:

// Maps input names to true/false whenever they have been "touched"
export type Touched<T> = {
  [key in keyof T]?: boolean;
};

// Form submit handlers must be asynchronous
export type SubmitHandler<T> = (values: T) => Promise<void>;

export interface Form<T> {
  // Input state
  values: T;
  touched: Touched<T>;
  errors: FormErrors<T>;

  // Indicates which input is focused, if any
  focused?: keyof T;

  // Form state
  isValid: boolean;
  isDirty: boolean;
  submitted: boolean;
  isSubmitting: boolean;
  handleChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
  handleBlur: (event: React.ChangeEvent<HTMLInputElement>) => void;
  handleFocus: (event: React.ChangeEvent<HTMLInputElement>) => void;
  handleSubmit: (
    fn: SubmitHandler<T>
  ) => (event: React.FormEvent<HTMLFormElement>) => void;
  reset: () => void;

  // Helper method to avoid repeating the same props for every input
  getInputProps: (name: keyof T) => {
    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
    onBlur: (event: React.ChangeEvent<HTMLInputElement>) => void;
    onFocus: (event: React.ChangeEvent<HTMLInputElement>) => void;
    value: T[keyof T];
    name: keyof T;
  };
}

Implenting our example

Using the above interface we can easily implement our example roughly as this:

import { useEffect } from "react";
import { useForm, type FormErrors } from "./useForm";

const initialValues = {
  name: "",
  surname: "",
};

type Schema = typeof initialValues;

async function submitHandler(values: Schema) {
  // ...
}

async function validate({
  name,
  surname,
}: Schema): Promise<FormErrors<Schema>> {
  const errors: FormErrors<Schema> = {};
  // ...
  return errors;
}

export function ExampleForm(): JSX.Element {
  const form = useForm({
    initialValues,
    validate,
  });

  const nameError =
    form.focused === "name"
      ? (form.errors.name ? "Enter your name capitalized" : "")
      : (form.touched.name ? form.errors.name : "");

  const lastnameError =
    form.focused === "surname"
      ? (form.errors.surname ? "Must be 'Doe'" || "")
      : (form.touched.surname ? form.errors.surname || "");

  const submitDisabled = form.isSubmitting || !form.isValid;

  return (
    <form onSubmit={form.handleSubmit(submitHandler)}>
      <div>
        <input
          disabled={form.isSubmitting}
          type="text"
          placeholder="Name"
          {...form.getInputProps("name")}
        />
        <p>{nameError}</p>
      </div>
      <div>
        <input
          disabled={form.isSubmitting}
          type="text"
          placeholder="Surname"
          {...form.getInputProps("surname")}
        />
        <p>{lastnameError}</p>
      </div>
      <button
        disabled={submitDisabled}
        type="submit"
      >
        Submit
      </button>
    </form>
  );
}

The implementation

Validation

The core part is handling async validation correctly. Here’s how we manage it:

const validate = async (newValues: T, name?: keyof T): Promise<void> => {
  const controller = new AbortController();

  // Abort ongoing validations
  validationController.current?.abort();
  validationController.current = controller;

  try {
    const validationErrors = await validateFn?.(newValues, {
      signal: controller.signal,
      name,
    });

    if (!controller.signal.aborted && validationErrors !== undefined) {
      setErrors((prevErrors) =>
        // Check if we wish partial or total errors update
        Array.isArray(validationErrors)
          ? { ...prevErrors, ...validationErrors[0] }
          : { ...validationErrors }
      );
    }
  } catch (error) {
    if (!controller.signal.aborted) {
      onError?.(error);
    }
  }
};

To prevent unnecessary API calls, we debounce the validation:

const validateDebounced = (newValues: T, name?: keyof T) => {
  clearTimeout(validationTimeoutHandler.current);
  validationTimeoutHandler.current = setTimeout(() => {
    validate(newValues, name);
  }, validationDelay);
};

This setup ensures that:

Only the most recent validation result is applied
Unnecessary API calls are cancelled
We don’t waste resources validating intermediate states

Async submission

Form submission often involves API calls, and handling the submission state correctly is crucial for UX. Our handler takes care of this automatically:

const handleSubmit: Form<T>["handleSubmit"] = (submitFn) => async (event) => {
  event.preventDefault();

  const touchedAll = Object.keys(values).reduce(
    (acc, key) => ({ ...acc, [key]: true }),
    {}
  );
  setTouched(touchedAll);
  setSubmitHandler(() => submitFn);
  setSubmitted(true);
};
// ...
useEffect(() => {
  if (submitHandler !== undefined) {
    // Only submit when form is valid
    const task = isValid ? submitHandler(values) : Promise.resolve();
    task.finally(() => {
      // This avoids React's warning 'State update on an unmounted component'
      if (!unmounted.current) {
        setSubmitHandler(undefined);
      }
    });
  }
}, [submitHandler, values, isValid]);

Entire implementation

Here’s how the entire implementation looks like:


54 collapsed lines
1
import { useEffect, useRef, useState } from "react";
2

3
export type Touched<T> = {
4
  [key in keyof T]?: boolean;
5
};
6

7
export type SubmitHandler<T> = (values: T) => Promise<void>;
8

9
export type FormErrors<T> = {
10
  [key in keyof T]?: string;
11
};
12

13
export interface FormOptions<T> {
14
  initialValues: T;
15
  isEqual?: (a: T, b: T) => boolean;
16
  validate?: (
17
    values: T,
18
    options: { signal: AbortSignal; name?: keyof T }
19
  ) =>
20
    | FormErrors<T>
21
    | [FormErrors<T>]
22
    | Promise<FormErrors<T> | [FormErrors<T>]>;
23
  validationDelay?: number;
24
  onError?: (error: unknown) => void;
25
}
26

27
export interface Form<T> {
28
  values: T;
29
  touched: Touched<T>;
30
  errors: FormErrors<T>;
31
  focused?: keyof T;
32
  isValid: boolean;
33
  isDirty: boolean;
34
  submitted: boolean;
35
  isSubmitting: boolean;
36
  handleChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
37
  handleBlur: (event: React.ChangeEvent<HTMLInputElement>) => void;
38
  handleFocus: (event: React.ChangeEvent<HTMLInputElement>) => void;
39
  handleSubmit: (
40
    fn: SubmitHandler<T>
41
  ) => (event: React.FormEvent<HTMLFormElement>) => void;
42
  reset: () => void;
43
  getInputProps: (name: keyof T) => {
44
    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
45
    onBlur: (event: React.ChangeEvent<HTMLInputElement>) => void;
46
    onFocus: (event: React.ChangeEvent<HTMLInputElement>) => void;
47
    value: T[keyof T];
48
    name: keyof T;
49
  };
50
}
51

52
export const defaultIsEqual = <T,>(a: T, b: T): boolean => a === b;
53
export const defaultValidationDelay = 200;
54

55
export function useForm<T extends Record<string, unknown>>({
56
  initialValues,
57
  validate: validateFn,
58
  isEqual = defaultIsEqual,
59
  validationDelay = defaultValidationDelay,
60
  onError,
61
}: FormOptions<T>): Form<T> {
62
  const [values, setValues] = useState(initialValues);
63
  const [errors, setErrors] = useState<FormErrors<T>>({});
64
  const [touched, setTouched] = useState<Touched<T>>({});
65
  const [submitted, setSubmitted] = useState(false);
66
  const [focused, setFocused] = useState<keyof T>();
67
  const [submitHandler, setSubmitHandler] = useState<SubmitHandler<T>>();
68

69
  const validationTimeoutHandler = useRef<NodeJS.Timeout | undefined>();
70
  const validationController = useRef<AbortController | undefined>();
71
  const unmounted = useRef(false);
72

73
  const isValid = Object.keys(errors).length === 0;
74
  const isDirty = !isEqual(values, initialValues);
75
  const isSubmitting = submitHandler !== undefined;
76

77
  const validate = async (newValues: T, name?: keyof T): Promise<void> => {
23 collapsed lines
78
    const controller = new AbortController();
79

80
    validationController.current?.abort();
81
    validationController.current = controller;
82

83
    try {
84
      const validationErrors = await validateFn?.(newValues, {
85
        signal: controller.signal,
86
        name,
87
      });
88

89
      if (!controller.signal.aborted && validationErrors !== undefined) {
90
        setErrors((prevErrors) =>
91
          Array.isArray(validationErrors)
92
            ? { ...prevErrors, ...validationErrors[0] }
93
            : { ...validationErrors }
94
        );
95
      }
96
    } catch (error) {
97
      if (!controller.signal.aborted) {
98
        onError?.(error);
99
      }
100
    }
101
  };
102

103
  const validateDebounced = (newValues: T, name?: keyof T) => {
4 collapsed lines
104
    clearTimeout(validationTimeoutHandler.current);
105
    validationTimeoutHandler.current = setTimeout(() => {
106
      validate(newValues, name);
107
    }, validationDelay);
108
  };
109

110
  const handleChange: Form<T>["handleChange"] = (event) => {
4 collapsed lines
111
    const { name, value } = event.target;
112
    const newValues = { ...values, [name]: value };
113
    setValues(newValues);
114
    validateDebounced(newValues, name as keyof T);
115
  };
116

117
  const handleBlur: Form<T>["handleBlur"] = (event) => {
4 collapsed lines
118
    const { name } = event.target;
119

120
    setTouched((prev) => ({ ...prev, [name]: true }));
121
    setFocused(undefined);
122
  };
123

124
  const handleFocus: Form<T>["handleFocus"] = (event) => {
3 collapsed lines
125
    const { name } = event.target;
126

127
    setFocused(name as keyof T);
128
  };
129

130
  const handleSubmit: Form<T>["handleSubmit"] = (submitFn) => async (event) => {
9 collapsed lines
131
    event.preventDefault();
132

133
    const touchedAll = Object.keys(values).reduce(
134
      (acc, key) => ({ ...acc, [key]: true }),
135
      {}
136
    );
137
    setTouched(touchedAll);
138
    setSubmitHandler(() => submitFn);
139
    setSubmitted(true);
140
  };
141

142
  const reset = () => {
5 collapsed lines
143
    setValues(initialValues);
144
    setFocused(undefined);
145
    setErrors({});
146
    setTouched({});
147
    setSubmitted(false);
148
  };
149

20 collapsed lines
150
  useEffect(() => {
151
    validate(values);
152

153
    return () => {
154
      unmounted.current = true;
155
      validationController.current?.abort();
156
      clearTimeout(validationTimeoutHandler.current);
157
    };
158
  }, []);
159

160
  useEffect(() => {
161
    if (submitHandler !== undefined) {
162
      const task = isValid ? submitHandler(values) : Promise.resolve();
163
      task.finally(() => {
164
        if (!unmounted.current) {
165
          setSubmitHandler(undefined);
166
        }
167
      });
168
    }
169
  }, [submitHandler, values, isValid]);
170

171
  return {
172
    values,
173
    errors,
174
    touched,
175
    focused,
176
    submitted,
177
    isValid,
178
    isDirty,
179
    isSubmitting,
180
    handleChange,
181
    handleBlur,
182
    handleFocus,
183
    handleSubmit,
184
    reset,
185
    getInputProps: (name) => ({
186
      onChange: handleChange,
187
      onBlur: handleBlur,
188
      onFocus: handleFocus,
189
      value: values[name],
190
      name,
191
    }),
192
  };
193
}

Conclusion

Building this form handler have solved my specific needs around async operations and type safety. While there are many form libraries available, sometimes building a custom solution that perfectly fits your needs is the right choice.