@bswohlers/lightform v1.0.0

LightForm

LightForm is a simple, lightweight hook for building forms in React. The simple and unopinionated API works with any kind of form built with React, even if you're not using react-dom.

Types

Validator

type Validator<K> = (value: unknown) => K;

A validator is a function that accepts any value and either returns the value (if it passes validation checks) or throws an error.

Hook

LightForm exposes one hook, useForm. At a high level, useForm accepts the initial state of the form fields, and corresponding validators for any of those fields. Validators is a Partial, so not every field needs a validator function.

The hook returns the following object, assuming that the type of the form's state is K:

{
  values: K;
  errors: Record<keyof K, string>;
  onFieldChange: (field: keyof K) => (value: K[keyof K]) => void;
  hasErrors: boolean;
}

values

An object containing the current values of the form. This will have the same shape as the initialState passed into the hook.

errors

An object containing a map of field names to error messages. An empty error message ("") indicates no error or the field has not yet been changed from its initial state. Note that if a field in initialState has an error, that error will not appear in this object until that field is modified. Therefore, use this object only for showing errors to the user and not for determining whether the form is submittable.

onFieldChange

A function that, when called with a field name, returns an onChange function for that field, which is used to change the value of that field.

hasErrors

A boolean indicating whether any of the fields in the form have errors. Note that this may be true even if errors has only empty strings; whereas the values of errors only populate after their fields have been modified, hasErrors will return true if the initialState contains an error. Therefore, use this to determine whether the form is submittable.