@swan-io/use-form

A simple, fast, and opinionated form library for React & React Native focusing on UX.
👉 Take a look at the demo website.

Setup

1$ npm install --save @swan-io/use-form
2# --- or ---
3$ yarn add @swan-io/use-form

Features

• Subscription-based field updates (avoid re-render the whole form on each keystroke 🔥)
• Validation strategies ✨
• Field sanitization
• Mounted-only fields validation
• Advanced focus handling
• Best-in-class TypeScript support
• Sync and async form submission

Motivation

Why another React form library 🤔?
Because, as silly as it seems, we couldn't find any existing library which fits our existing needs:

• We want validation strategies per field because we fell in love with them when we read the re-formality documentation (which is unfortunately only available for ReScript).
• It should be able to handle huge forms without a single performance hiccup.
• Validation should be simple, reusable, and testable (aka just functions).
• It shouldn't even try to validate unmounted fields.
• It should have built-in focus management (to improve the keyboard flow of our React Native forms).

Validation strategies ✨

The key of good UX is simple: validation should be executed in continue, feedback should be provided when it makes sense.

Quick example: A credit card field 💳

Let's say we want to display a valid state icon (✔) when the input value is a valid credit card number but don't want to display an error until the user blurs the field (and lets the value in an invalid state).

Something like this:

How do we easily achieve such magic? With the onSuccessOrBlur strategy 🧙‍♂️

1const {} = useForm({
2  cardNumber: { initialValue: "", strategy: "onSuccessOrBlur" },
3});

Of course, onSuccessOrBlur will not fit perfectly every use-case!
That's precisely why every field config could declare its own strategy:

Strategy	When feedback will be available?
onChange	On first change (as the user types or update the value)
onSuccess	On first validation success
onBlur	On first field blur
onSuccessOrBlur	On first validation success or first field blur (default)
onSubmit	On form submit

Note that:

• The strategies will only be activated after the field value update / the form submission.
• Once the first feedback is given (the field is valid or should display an error message), the field switches to what we call "talkative" state. After that, feedback will be updated on each value change until this field or the form is reset.

API

⚠️ The API is described using TypeScript pseudocode.
These types are not exported by the library / are not even always valid.

useForm

useForm takes one argument (a map of your fields configs) and returns a set of helpers (functions, components, and values) to manage your form state.

1import { useForm } from "@swan-io/use-form";
2
3const {
4  formStatus,
5  Field,
6  FieldsListener,
7  getFieldValue,
8  getFieldRef,
9  setFieldValue,
10  setFieldError,
11  focusField,
12  resetField,
13  sanitizeField,
14  validateField,
15  listenFields,
16  resetForm,
17  submitForm,
18} = useForm({
19  // Keys are used as fields names
20  fieldName: {
21    initialValue: "",
22    // Properties below are optional (those are the default values)
23    strategy: "onSuccessOrBlur",
24    isEqual: (value1, value2) => Object.is(value1, value2),
25    sanitize: (value) => value,
26    validate: (value, { focusField, getFieldValue }) => {},
27  },
28});

Field config

1type fieldConfig = {
2  // The initial field value. It could be anything (string, number, boolean…)
3  initialValue: Value;
4
5  // The chosen strategy. See "validation strategies" paragraph
6  strategy: Strategy;
7
8  // Used to perform initial and current value comparaison
9  isEqual: (value1: Value, value2: Value) => boolean;
10
11  // Will be run on value before validation and submission. Useful from trimming whitespaces
12  sanitize: (value: Value) => Value;
13
14  // Used to perform field validation. It could return an error message (or nothing)
15  validate: (value: Value) => ErrorMessage | void;
16};

formStatus

1type formStatus =
2  | "untouched" // no field has been updated
3  | "editing"
4  | "submitting"
5  | "submitted";

<Field />

A component that exposes everything you need locally as a children render prop.

1<Field name="fieldName">
2  {
3    (props: {
4      // A ref to pass to your element (only required for focus handling)
5      ref: MutableRefObject;
6      // The field value
7      value: Value;
8      // Is the field valid?
9      valid: boolean;
10      // The field is invalid: here its error message.
11      error?: ErrorMessage;
12      // The onBlur handler (required for onBlur and onSuccessOrBlur strategies)
13      onBlur: () => void;
14      // The onChange handler (required)
15      onChange: (value: Value) => void;
16    }) => /* … */
17  }
18</Field>

<FieldsListener />

A component that listens for fields states changes. It's useful when a part of your component needs to react to fields updates without triggering a full re-render.

1<FieldsListener names={["firstName", "lastName"]}>
2  {
3    (states: Record<"firstName" | "lastName", {
4      // The field value
5      value: Value;
6      // Is the field valid?
7      valid: boolean;
8      // The field is invalid: here its error message.
9      error?: ErrorMessage;
10    }>) => /* … */
11  }
12</FieldsListener>

getFieldValue

By setting sanitize: true, you will enforce sanitization.

1type getFieldValue = (
2  name: FieldName,
3  options?: {
4    sanitize?: boolean;
5  },
6) => Value;

getFieldRef

Return the field stable ref.

1type getFieldRef = <T>(name: FieldName) => MutableRefObject<T>;

setFieldValue

By setting validate: true, you will enforce validation. It has no effect if the field is already talkative.

1type setFieldValue = (
2  name: FieldName,
3  value: Value,
4  options?: {
5    validate?: boolean;
6  },
7) => void;

setFieldError

Will make the field talkative.

1type setFieldError = (name: FieldName, error?: ErrorMessage) => void;

focusField

Will only work if you forward the Field provided ref to your input.

1type focusField = (name: FieldName) => void;

resetField

Hide user feedback (the field is not talkative anymore) and set value to initialValue.

1type resetField = (name: FieldName) => void;

sanitizeField

Sanitize the field value.

1type sanitizeField = (name: FieldName) => void;

validateField

Once you manually call validation, the field automatically switches to talkative state.

1type validateField = (name: FieldName) => ErrorMessage | void;

listenFields

A function that listen for fields states changes. Useful when you want to apply side effects on values change.

1React.useEffect(() => {
2  const removeListener = listenFields(
3    ["firstName", "lastName"],
4    (states: Record<"firstName" | "lastName", {
5      // The field value
6      value: Value;
7      // Is the field valid?
8      valid: boolean;
9      // The field is invalid: here its error message.
10      error?: ErrorMessage;
11    }>) => /* … */
12  );
13
14  return () => {
15    removeListener();
16  }
17}, []);

resetForm

Hide user feedback for all fields (they are not talkative anymore). Reset values to their corresponding initialValue and formStatus to untouched.

1type resetForm = () => void;

submitForm

Submit your form. Each callback could return a Promise to keep formStatus in submitting state.

1type submitForm = (options?: {
2  onSuccess?: (values: OptionRecord<Values>) => Future<unknown> | Promise<unknown> | void;
3  onFailure?: (errors: Partial<Record<keyof Values, ErrorMessage>>) => void;
4  // by default, it will try to focus the first errored field (which is a good practice)
5  focusOnFirstError?: boolean;
6}) => void;

combineValidators

As it's a very common case to use several validation functions per field, we export a combineValidators helper function that allows you to chain sync validation functions: it will run them sequentially until an error is returned.

1import { combineValidators, useForm } from "@swan-io/use-form";
2
3const validateRequired = (value: string) => {
4  if (!value) {
5    return "required";
6  }
7};
8
9const validateEmail = (email: string) => {
10  if (!/.+@.+\..{2,}/.test(email)) {
11    return "invalid email";
12  }
13};
14
15const MyAwesomeForm = () => {
16  const { Field, submitForm } = useForm({
17    emailAddress: {
18      initialValue: "",
19      // will run each validation function until an error is returned
20      validate: combineValidators(
21        isEmailRequired && validateRequired, // validation checks could be applied conditionally
22        validateEmail,
23      ),
24    },
25  });
26
27  // …
28};

toOptionalValidator

Very often, we want to execute validation only if a value is not empty. By wrapping any validator (or combined validators) with toOptionalValidator, you can bypass the validation in such cases.

1import { toOptionalValidator, Validator } from "@swan-io/use-form";
2
3// This validator will error if the string length is < 3 (even if it's an empty string)
4const validator: Validator<string> = (value) => {
5  if (value.length < 3) {
6    return "Must be at least 3 characters";
7  }
8};
9
10// This validator will error if value is not empty string and if the string length is < 3
11const optionalValidator = toOptionalValidator(validator);

This function also accept a second param (required for non-string validators) to specify what is an empty value.

1import { toOptionalValidator, Validator } from "@swan-io/use-form";
2
3const validator: Validator<number> = (value) => {
4  if (value < 10) {
5    return "Must pick at least 10 items";
6  }
7};
8
9// This validator will also accept a value of 0, as we consider it "empty"
10const optionalValidator = toOptionalValidator(validator, (value) => value === 0);

Quickstart

1import { useForm } from "@swan-io/use-form";
2
3const MyAwesomeForm = () => {
4  const { Field, submitForm } = useForm({
5    firstName: {
6      initialValue: "",
7      strategy: "onSuccessOrBlur",
8      sanitize: (value) => value.trim(), // we trim value before validation and submission
9      validate: (value) => {
10        if (value === "") {
11          return "First name is required";
12        }
13      },
14    },
15  });
16
17  return (
18    <form
19      onSubmit={(event: React.FormEvent) => {
20        event.preventDefault();
21
22        submitForm({
23          onSuccess: (values) => console.log("values", values), // all fields are valid
24          onFailure: (errors) => console.log("errors", errors), // at least one field is invalid
25        });
26      }}
27    >
28      <Field name="firstName">
29        {({ error, onBlur, onChange, valid, value }) => (
30          <>
31            <label htmlFor="firstName">First name</label>
32
33            <input
34              id="firstName"
35              onBlur={onBlur}
36              value={value}
37              onChange={({ target }) => {
38                onChange(target.value);
39              }}
40            />
41
42            {valid && <span>Valid</span>}
43            {error && <span>Invalid</span>}
44          </>
45        )}
46      </Field>
47
48      <button type="submit">Submit</button>
49    </form>
50  );
51};

More examples

A full set of examples is available on the demo website or in the /website directory project. Just clone the repository, install its dependencies and start it!

Acknowledgements

• re-formality for the validation strategies idea.
• react-hook-form and react-final-form for their subscription pattern implementations.