# reactjs-use-form

> Reactive form management and input field validation hook

Latest version **1.7.6** (published 2026-09-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install reactjs-use-form
pnpm add reactjs-use-form
yarn add reactjs-use-form
bun add reactjs-use-form
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.7.6 |
| Published | 2026-09-06 |
| First published | 2021-07-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 21.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | amir0ff |
| Maintainers | amiroff157 |
| Keywords | react, typescript, react-testing-library, react-hooks |

## Links

- npm: https://www.npmjs.com/package/reactjs-use-form
- Repository: https://github.com/amir0ff/reactjs-use-form
- Homepage: https://amir0ff.github.io/reactjs-use-form
- Issues: https://github.com/amir0ff/reactjs-use-form/issues
- npm.io page: https://npm.io/package/reactjs-use-form

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.7.6 (latest) — 2026-09-06
- 1.5.0-beta.0 (beta) — 2023-01-23
- 1.7.5 — 2026-05-23
- 1.7.4 — 2026-05-19
- 1.7.3 — 2026-01-24
- 1.7.1 — 2025-07-17
- 1.7.0 — 2025-07-17
- 1.6.9 — 2025-07-17
- 1.6.8 — 2025-07-17
- 1.6.7 — 2025-07-17
- 1.6.6 — 2025-07-17
- 1.6.5 — 2025-07-17
- 1.6.3 — 2025-07-17
- 1.6.2 — 2025-07-17
- 1.6.1 — 2025-07-17
- … 48 more at https://npm.io/package/reactjs-use-form/versions

## README

# useForm(📋, ⚙️) ⇒ Reactive Form ⚛️

[![build and tests](https://github.com/amir0ff/reactjs-use-form/actions/workflows/ubuntu_node.yml/badge.svg)](https://github.com/amir0ff/reactjs-use-form/actions/workflows/ubuntu_node.yml)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/amir0ff/reactjs-use-form)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![bundle size](https://deno.bundlejs.com/badge?q=reactjs-use-form@1.7.6)](https://bundlejs.com/?q=reactjs-use-form@1.7.6)
[![typescript](https://img.shields.io/npm/types/reactjs-use-form?label=with)](https://github.com/amir0ff/reactjs-use-form/blob/main/docs/definitions.md)

#### The most lightweight React form management library with TypeScript support

> Create a [form model](#usage), 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

```bash
# npm
npm install reactjs-use-form

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

# yarn
yarn add reactjs-use-form
```

- 🧪 Tested using [@testing-library/react](https://www.npmjs.com/package/@testing-library/react).
- 🏗️ Built with [Vite](https://vitejs.dev) in library mode.
- ⚡ Modern TypeScript 6 with strict type checking.

## Usage

##### Steps:

1. create a form model:

```tsx
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' : '';
    },
  },
};
```

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

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

<details>
<summary> Plain JSX code example </summary>

```tsx
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>
  );
};
```

</details>

## Options

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

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

| Property           | Type                                                           | Description                                               |
| ------------------ | -------------------------------------------------------------- | --------------------------------------------------------- |
| values             | [`ValuesType`](https://github.com/amir0ff/reactjs-use-form/blob/main/docs/definitions.md#valuestype)                 | current form values state object                          |
| errors             | [`ErrorsType`](https://github.com/amir0ff/reactjs-use-form/blob/main/docs/definitions.md#errorstype)                 | current form errors state object                          |
| handleOnChange     | [`HandleOnChangeType`](https://github.com/amir0ff/reactjs-use-form/blob/main/docs/definitions.md#handleonchangetype) | handler for input field changes                          |
| handleOnSubmit     | [`HandleOnSubmitType`](https://github.com/amir0ff/reactjs-use-form/blob/main/docs/definitions.md#handleonsubmittype) | handler for form submission                              |
| isDisabled         | `boolean`                                                      | whether form submit button should be disabled            |
| isSubmitted        | `boolean`                                                      | whether form has been successfully submitted             |
| isSubmitting       | `boolean`                                                      | whether form is currently being submitted                |
| isDirty            | `boolean`                                                      | whether any form field has been modified since init/submit |
| resetForm          | `() => void`                                                   | function to reset entire form                            |
| resetField         | `(fieldName: keyof T) => void`                                | function to reset specific field                         |
| formModel          | [`FormModelType`](https://github.com/amir0ff/reactjs-use-form/blob/main/docs/definitions.md#formmodeltype)           | initial form model with optional validation function      |
| formSubmitCallback | `(values: T) => void \| Promise<void>`                        | async callback function executed on successful form submission |

#### Type definitions: [docs/definitions.md](https://github.com/amir0ff/reactjs-use-form/blob/main/docs/definitions.md)

## License

![GitHub](https://img.shields.io/github/license/amir0ff/reactjs-use-form?color=blue)

---
_Source: https://npm.io/package/reactjs-use-form · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._