React Use Form Library

A simple form libray for React using hooks.

Motivation

The motivation for working on this solution for form handling comes from the fact that we wanted something very simple and straighforward to use, while also being as agnostic to the implementation as possible, to make it easy to integrate in every kind of project.

Contrary to other solutions that provide you with react components and/or wrappers, we went for a simple react hook that gives you all the tools needed to implement your forms as you see fit.

Easy to use: you supply a model and a submit function to the hook and you get back helpers to use in your inputs.
Small: the codebase is quite simple and small. Currently only under 7kb gzipped.
Declarative: we use the same handlers as the native inputs { value, onChange, onBlur }.

Installation
Basic Example
Optional fields
Validation
Error Handling
Advanced Example
Nested Objects
Array values (FieldSet)
API
Development

Installation

Add the library to your project:

yarn add @nerdgeschoss/react-use-form-library

npm install @nerdgeschoss/react-use-form-library

Basic example

Codepen

To initialize the hook you will need to supply a valid model object and a custom onSubmit function.

The three main fields you get from the hook are model, fields and onSubmit.

model is the updated object which will contain the modified fields.
fields is an object in which each key will be generated from properties of the original model you supplied to the hook.
onSubmit is the handler you can provide to the <form> element. It will call preventDefault internally and execute the function provided to the hook as onSubmit

import { useForm } from '@nerdgeschoss/react-use-form-library';

function App(): JSX.Element {
  const { fields, onSubmit } = useForm({
    model: {
      name: '',
    },
    onSubmit: async ({ model }) => {
      console.log(model);
    },
  });

  return (
    <form onSubmit={onSubmit}>
      <input
        value={fields.name.value}
        onChange={(v) => fields.name.onChange(v.target.value)}
      />
      <button>Submit</button>
    </form>
  );
}

Optional Fields

You don't need to explicitly enumerate all properties in your model, the library will generate all necesary fields on demand by using Proxy.

import { useForm } from '@nerdgeschoss/react-use-form-library';

function App(): JSX.Element {
  const { fields, onSubmit } = useForm({
    // You can supply an empty object
    model: {},
    onSubmit: async ({ model }) => {
      console.log(model);
    },
  });

  return (
    <form onSubmit={onSubmit}>
      <input
        value={fields.name.value}
        onChange={(v) => fields.name.onChange(v.target.value)}
      />
      <input
        value={fields.phone.value}
        onChange={(v) => fields.phone.onChange(v.target.value)}
      />
      <button>Submit</button>
    </form>
  );
}

If you use Typescript you will have to supply the interface for your model

// ...
const { model, fields, onSubmit } = useForm<{ name?: string; phone?: number }>({
  model: {},
  onSubmit: async () => {
    console.log(model);
  },
});
// ...

Validation

Codepen

The validations object needs to correspond your model object. Each key can take one of the following values:

A string that contains prebuild common validations. Currently supported are: required, email, number and more.
A custom validation function with the signature (value: model): string[] => {}. The value parameter is useful to supply the updated model and make comparisons. For this validation to report an error you have to return an array of strings. Each string is supposed to be an error that you can later display in the UI.
An array which can contain the previous both.

const { model, fields, onSubmit, valid } = useForm({
  model: {
    name: '',
    phone: '',
    customRegex: '',
    email: '',
    emailConfirmation: '' ,
  },
  validations: {
    // A single string
    name: 'required',
    // A function
    phone: (model) => {
      if (isNaN(model.phone)) {
        return ['not a number'];
      }
    },
    // A Regex
    customRegex: /[a-g]/,
    // A combination
    email: ['required', 'email']
    emailComfirmation: [
      'required',
      'email',
      (model) => {
        if (model.email !== model.emailConfirmation) {
          return ['Email must be the same']
        }
      }
    ]
  },
});

Predefined validation strings

Property	Details
required	checks if the field is not empty.
email	checks if the value is a valid email address.
json	checks if the value is a valid json object.
website	checks if the value is a valid website (http / https).
number	checks if the value is a number.

Submit Error Handling

Codepen

The hook also exposes another method: onSubmitError, which is handy if you don't want to use a try/catch in your onSubmit function.

const { model, fields, onSubmit, valid } = useForm({
  model: {
    name: '',
    phone: '',
  },
  onSubmit: async () => {
    throw new Error('submit error');
  },
  onSubmitError: (error) => {
    alert('error');
  },
});

Form state

Codepen

There are several properties exposed from the hook to deal with the state throughout the form lifetime

Property	Details
dirty	A boolean value indicating that one or more fields have been changed
valid	A boolean indicating that the form is valid or not, this one depends on the validation rules provided.
error	any error thrown within the onSubmit function is stored here as an error object
submissionStatus	Displays the current status of the submission process

Submission Status

This variable contains the current state of the form submission process. At any time the form will be in one of the following states:

Status	Details
idle	The form has not yet been submitted. It also applied when the form is reset
submitting	The form is being submitted. This works like a loading state.
submitted	The form has been successfully submitted.
error	There is an error while submitting.

Reset

Sometimes it is useful to reset the form programatically. For this there are two helpful methods:

Property	Details
reset	Clears all fields.
resetError	Removes the current error.

Fields

Codepen

Every key supplied to the model property of the hook will be parsed into a field

// ...
const { fields } = useForm({
  model: {
    name: '',
  },
});
// ...

A field will be an object that you can use in a simple setup like:

// ...
<input
  // The updated value
  value={fields.phone.value}
  // A function to modify the value
  onChange={(v) => fields.phone.onChange(v.target.value)}
/>
// ...

Or a more complex solution:

// ...
<div>
  // The required property is derived from the validation of the field
  <label>Name {fields.name.required ? '(required)' : ''}: </label>
  <input
    value={fields.name.value}
    onChange={(v) => fields.name.onChange(v.target.value)}
  />
  // The errors property is an array of strings with all errors for the field
  {fields.name.errors.length && (
    <div>
      {fields.errors.forEach((error) => {
        return <div>{error}</div>;
      })}
    </div>
  )}
</div>
// ...

Helpful properties

touched

If the field is required, the required-field error will always be present if the value is empty. It is good UX to only display the required error if the field has been touched, for this you can use the touched property which will be true once the field has lost focus for the first time (onBlur event).

Important !!

If you want to immediately display errors based on the touched property, you need to add the onBlur event to your input. Otherwise it will only be displayed after an update event triggered by onChange.

Submitting the form will also "touch" all fields, to make sure errors are displayed if the form is invalid.

// ...
const displayErrors = fields.name.touched && fields.name.errors.length;

<div>
  <input
    value={fields.name.value}
    onChange={(v) => fields.name.onChange(v.target.value)}
    onBlur={fields.name.onBlur}
  />
  {
    displayErrors && (
      <div>
        {fields.errors.forEach((error) => {
          return <div>{error}</div>;
        })}
      </div>
    );
  }
</div>
// ...

valid

A simple getter that returns true if there aren't any errors. This would simplify the above conditional to:

const displayErrors = fields.name.touched && !fields.name.valid;

It is also useful if you want to give your input a conditional class to show the user if the field is valid or not

<div className={fields.phone.valid ? 'input--valid' : ''}>
  <input
    value={fields.phone.value}
    onChange={(v) => fields.phone.onChange(v.target.value)}
  />
</div>

dirty

When instantiated, a field will store it's original value in a variable. This getter will then compare the original value to the current value and return true if they are different.

Advanced example

import { useForm } from '@nerdgeschoss/react-use-form-library';

export function MyForm({ isNewItem, addItem, updateItem }: Props): JSX.Element => {
  const { fields, onSubmit, submissionStatus } = useForm({
    model: {
      name: '',
      age: 25,
    },
    onSubmit: async ({model, changes, reset}) => {
      if (isNewItem) {
        // You can use here the updated model, which includes the original model and any changes made
        await addItem(model);
      } else {
        // For updating, you can use only the changes that were made
        await updateItem(changes);
      }
      // If you need to clear the fields, you can call on reset form
      reset();
    },
    // Handle any errors
    onSubmitError: (error) => {
      alert('error');
    },
  });

  return (
    <div>
      <form onSubmit={onSubmit}>
        <input
          value={fields.name.value}
          onChange={(v) => fields.name.onChange(v.target.value)}
        />
        <input
          value={fields.age.value}
          // Make sure you parse the value to be consistent with the model
          onChange={(v) => fields.age.onChange(Number(v.target.value))}
        />
        // You can use submitting to display loading state
        {submissionStatus === 'submitting' ? (
          <div>Loading...</div>
        ) : (
          // Valid state can also be used to disable submit
          <button disabled={!valid || !dirty}>Submit</button>
        )}
      </form>
    </div>
  );
}

Nested Objects

Each FormField object is also able to contain fields. It behaves similarly to the Form object but with slight differences in its methods (See API).

import { useForm } from '@nerdgeschoss/react-use-form-library';

function App(): JSX.Element {
  const { fields, onSubmit } = useForm({
    model: {
      address: {
        streetName: '',
      },
    },
    onSubmit: async ({ model }) => {
      console.log(model);
    },
  });

  return (
    <form onSubmit={onSubmit}>
      <input
        value={fields.address.fields.streetName.value}
        onChange={(v) =>
          fields.address.fields.streetName.onChange(v.target.value)
        }
      />
      <button>Submit</button>
    </form>
  );
}

Validations also work with nested objects

import { useForm } from '@nerdgeschoss/react-use-form-library';

function App(): JSX.Element {
  const { fields, onSubmit } = useForm({
    model: {
      address: {
        streetName: '',
      },
    },
    onSubmit: async ({ model }) => {
      console.log(model);
    },
    validations: {
      address: {
        streetName: 'required',
      },
    }
  });

  // ...

Since the fields property within FormField is also based on a Proxy object, you can access nested properties without explicitely declaring them

function App(): JSX.Element {
  /* If you use Typescript you have to define the model interface, otherwise you'll get an error
  while trying to access the nested properties */
  const { fields, onSubmit } = useForm<{
    bankDetails?: {
      address?: {
        screetName: string;
      };
    };
  }>({
    model: {},
    onSubmit: async ({ model }) => {
      console.log(model);
    },
  });

  return (
    <form onSubmit={onSubmit}>
      <input
        value={fields.bankDetails.fields.address.fields.streetName.value}
        onChange={(v) =>
          fields.bankDetails.fields.address.fields.streetName.onChange(
            v.target.value
          )
        }
      />
      <button>Submit</button>
    </form>
  );
}

FieldSet

A FieldSet is basically an array of FormFields. Contrary to nested objects, a FieldSet will only be instantiated if it is explicitly declared in the model.

Important !!

If you don't initialize the property in the model and try to access it in your code you will get an error.

This is because at the moment of field instantiation, the addField method within a Form (or a FormField if it is a nested object) will ask if the model value is actually an Array. It is not possible to implicitly determine if the field is array-based only from the type definition.

const { fields } = useForm<{ emails: string[]; images: string[] }>({
  model: {
    images: [],
  },
});

return (
  <form onSubmit={onSubmit}>
    /* This will result in an error because emails has been instantiated as a
    FormField not as a FieldSet */
    {fields.emails.elements.map((field) => {
      // ...
    })}
    /* This will work as intented */
    {fields.images.elements.map((field) => {
      // ...
    })}
  </form>
);

The FieldSet object has a elements property, which is an array of FormField (more in the API)

function App(): JSX.Element {
  const { fields, onSubmit } = useForm({
    model: {
      emails: ['example@email.com'],
    },
    onSubmit: async ({ model }) => {
      console.log(model);
    },
  });

  return (
    <form onSubmit={onSubmit}>
      // a FieldSet fields property is iterable
      {fields.emails.fields.map((field) => {
        // Every FieldSet field is a FormField
        return (
          <div className="input">
            <input
              value={field.value}
              onChange={(v) => field.onChange(v.target.value)}
            />
            // FormFields regenerated from a FieldSet also have a remove method
            <button onClick={() => field.remove()}>remove</button>
          </div>
        );
      })}
      // FieldSet also has an insert method to create new items
      <button onClick={() => fields.emails.add('')}>Add Field</button>
      <button>Submit</button>
    </form>
  );
}

Removing Items

FormField objects inside a FieldSet include a remove method to remove the corresponding element..

<button onClick={() => fields.emails.fields[0].remove()}>remove</button>

Validating a FieldSet

A FieldSet takes the same kind of validation as any other field. On instantiation it will be saved in memory and it will be further applied to any new field created.

useForm({
  model: {
    // Initialize the field
    emails: [],
  },
  validations: {
    // Will be applied to any item added to emails
    emails: ['required', 'email'],
  },
});

If the validation is of the type required, it will also make the field invalid unless it has at least one element.

useForm({
  model: {
    // emails.valid will be false because we're initializing it with no elements.
    emails: [],
  },
  validations: {
    emails: 'required',
  },
});

Advanced FieldSet

A common escenario would be to have an array of objects in your model.

const { fields, onSubmit } = useForm<{
  images: Array<{
    id: string;
    url?: string;
  }>;
}>({
  model: {
    // Initialize the field
    images: [],
  },
});

return (
  <form onSubmit={onSubmit}>
    {fields.images.fields.map((field) => {
      return (
        <div className="input">
          /* You can access a property whithin the field, as you would with a
          nested object */
          <input
            value={field.fields.url.value}
            onChange={(v) => field.fields.url.onChange(v.target.value)}
          />
          <button onClick={() => field.remove()}>remove</button>
        </div>
      );
    })}
    <button
      onClick={() =>
        fields.images.insert({
          id: generateId(),
        })
      }
    >
      Add Field
    </button>
    <button>Submit</button>
  </form>
);

API

useForm

Props

Property	Details
model	Your form model, it should be an object (can be empty). Every property will be mapped into a field.
validations	A validations object.
onSubmit	Your custom submit function. It will be parsed internally and provide a onSubmit handler to call programaticaly.
onSubmitError	A useful handler to deal with errors.
onChange	A handler for changes in all form fields.

Form

Property	Details
changes	A plain object that contains only the modified fields
model	An updated object that contains the updated model
fields	A mapped collection, which has a FormField for every key in the model
dirty	a getter checking if there are any changes
valid	a getter checking if all required fields are valid
onSubmit	a method that triggers the function passed as onSubmit param.
submitting	a loading state for the onSubmit method
reset	this helper method will reset every field to it's original value

Form Field

Property	Details
value	the updated value of the current field
required	a required field useful to determine a valid state for the form
errors	a string array containing any errors
validation	a validation object that is triggered on every update
focused	a boolean stating if the field is currently in focus, you'll need to use onFocus/onBlur to change this state
onChange	a value change method, sets touched to true and triggers an update
onBlur	this method sets the touched state to true and focused to false
onFocus	sets focused to true
hasValue	a helper method to determine empty state. Checks for empty strings
validate	a validation function triggered on every update
setTouched	takes a boolean and will set the touched state to this value
reset	a helper method that resets the field to it's original value
valid	a getter that checks if the field has any errors
dirty	a getter that compares the current value to the original value passed on instantiation
touched	a touched state, initially false and changed to true when calling onChange/onBlur
remove	Only within a `FieldSet`, it removes the object from the collection

Nested Fields

These following methods will behave differently if the FormField has nested fields

Property	Details
onChange	It takes an object and will create/update every field from the keys of this object
hasValue	It is true when all fields have value
validate	It will run validations for all nested fields
setTouched	Takes a booleand and will set every nested field touched property to this value
reset	It resets the value of every nested field
touched	Will be touched when every fields is touched
valid	Will be valid when every fields is touched
dirty	Will be valid when at least one field is dirty
fields	A mapped collection, which has a FormField for every key in the value

FieldSet

Property	Details
fields	An array of FormField objects
onChange	Useful to update many fields at the same time. It takes an array value and will update every field based on the index. If the passed array is longer than the generated items, it will create more
setTouched	It takes a boolean parameter and will set every item touched property to this value
reset	It resets every field
validate	It validates every field
insert	It takes a comma separated array of arguments and adds a new FormField for each value
removeField	It removes a field given an object reference value
value	It returns an array with the value of every FormField item
dirty	Will be true if any item is dirty
touched	Will be true if every item is touched

Development

Install dependencies with yarn install. You can run interactive tests with yarn test and lint your project with yarn lint.

If you work with VSCode, it automatically switches to the correct TS version and formats on save via prettier. There is also an included launch config, so you can run and debug tests.

The VSCode Jest Extension is highly recommended as it gives you inline test results, code coverage and debugging right within VSCode (VSCode will automatically prompt you to install this extension).

Releases are done via GitHub Releases. Create a new release there, this will automatically trigger a workflow to publish the package.

Sandbox App

There is a also a sandbox basic application to play around with the library. Use yarn start to start up the parcel server, and you can find the files inside the /sandbox-app folder.

Troubleshoot

Sometimes you may get the following bug/error from parcel:

Conflicting babel versions found in .babelrc.

To solve this, after you started the dev server, go to the .babelrc file and comment these two lines:

{
  "presets": ["@babel/preset-env", "@babel/preset-typescript"],
  "plugins": [
    // "@babel/plugin-transform-runtime",
    // "babel-plugin-transform-class-properties"
  ]
}

After the server starts correctly you should uncomment those lines. If you still have some issues, try restarting the dev server.

React Use Form Library

Motivation

Table of Contents

Installation

Basic example

Optional Fields

Validation

Predefined validation strings

Submit Error Handling

Form state

Submission Status

Reset

Fields

Helpful properties

touched

valid

dirty

Advanced example

Nested Objects

FieldSet

Removing Items

Validating a FieldSet

Advanced FieldSet

API

useForm

Props

Form

Form Field

Nested Fields

FieldSet

Development

Sandbox App

Troubleshoot