reactjs-use-form

useForm(, ) ⇒ Reactive Form

The most lightweight React form management library with TypeScript support

Create a form model, flag input fields as required or add a value validation function with custom error messages. useForm will validate the inputs as the user types, when there are no errors the form gets enabled for submission. On form submission, it executes a callback function the user provides.

Requirements:

• Form model with optional validation function.
• Function to run after form validation and submission.
• React functional component with a form.

Install

# npm
npm install reactjs-use-form

# pnpm (recommended)
pnpm add reactjs-use-form

# yarn
yarn add reactjs-use-form

• Tested using @testing-library/react.
• Built with Vite in library mode.
• Modern TypeScript 6 with strict type checking.

Usage

Steps:

1. create a form model:

import type { FormModelType } from 'reactjs-use-form';

export interface ChangePasswordForm {
  currentPassphrase: string;
  newPassphrase: string;
  verifyPassphrase: string;
}

export const formModel: FormModelType<ChangePasswordForm> = {
  currentPassphrase: {
    value: '',
    required: true,
  },
  newPassphrase: {
    value: '',
    required: true,
    // `values` enables cross-field checks; peers revalidate when related fields change
    validator: (newPassphrase, values) => {
      if (newPassphrase === values?.currentPassphrase) {
        return 'New password must be different from current password';
      } else if (newPassphrase.length <= 5) {
        return 'Password must be at least 6 characters long';
      } else if (newPassphrase !== values?.verifyPassphrase) {
        return 'Passwords do not match';
      } else return '';
    },
  },
  verifyPassphrase: {
    value: '',
    required: true,
    validator: (verifyPassphrase, values) => {
      return verifyPassphrase !== values?.newPassphrase ? 'Passwords do not match' : '';
    },
  },
};

1. prepare a submit callback that receives the validated values, for example: async function handleSubmit(values: ChangePasswordForm) {...}.

2. use the form model with the callback function in useForm hook in a functional react component:

import { useForm } from 'reactjs-use-form';
import { formModel, type ChangePasswordForm } from './formModel';

const ChangePassphraseComponent = () => {
  const {
    values,
    errors,
    handleOnChange,
    handleOnSubmit,
    isDisabled,
    isSubmitted,
    isSubmitting,
    resetForm,
    resetField,
  } = useForm(formModel, handleSubmit);

  const { currentPassphrase, newPassphrase, verifyPassphrase } = values;

  async function handleSubmit(formValues: ChangePasswordForm) {
    // call your API with formValues
    console.log(formValues);
  }

  return (
    <form onSubmit={handleOnSubmit}>
      <div>
        <label>Current Passphrase</label>
        <input
          type="password"
          name="currentPassphrase"
          value={currentPassphrase}
          onChange={handleOnChange}
        />
        <span>{errors.currentPassphrase.message}</span>
        <button type="button" onClick={() => resetField('currentPassphrase')}>
          Clear
        </button>
      </div>
      <div>
        <label>New Passphrase</label>
        <input
          type="password"
          name="newPassphrase"
          value={newPassphrase}
          onChange={handleOnChange}
        />
        <span>{errors.newPassphrase.message}</span>
        <button type="button" onClick={() => resetField('newPassphrase')}>
          Clear
        </button>
      </div>
      <div>
        <label>Verify Passphrase</label>
        <input
          type="password"
          name="verifyPassphrase"
          value={verifyPassphrase}
          onChange={handleOnChange}
        />
        <span>{errors.verifyPassphrase.message}</span>
        <button type="button" onClick={() => resetField('verifyPassphrase')}>
          Clear
        </button>
      </div>
      <span>{isSubmitted ? 'Passphrase has been changed!' : null}</span>
      <button type="submit" disabled={isDisabled}>
        <span>{isSubmitting ? 'Changing...' : 'Submit'}</span>
      </button>
      <button type="button" onClick={resetForm}>
        Reset Form
      </button>
    </form>
  );
};

Options

useForm takes two params: formModel and formSubmitCallback and returns the rest.

const {
  values,
  errors,
  handleOnChange,
  handleOnSubmit,
  isDisabled,
  isSubmitted,
  isSubmitting,
  isDirty,
  resetForm,
  resetField,
} = useForm(formModel, formSubmitCallback);

Type definitions: docs/definitions.md

License