# form-model-hook

> A very simple hook to abstract common patterns on form data and validation.

Latest version **1.0.9** (published 2022-07-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install form-model-hook
pnpm add form-model-hook
yarn add form-model-hook
bun add form-model-hook
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.9 |
| Published | 2022-07-26 |
| First published | 2022-07-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=8 |
| Dependencies | 0 |
| Unpacked size | 629.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | marcosap |
| Maintainers | mapereira |

## Links

- npm: https://www.npmjs.com/package/form-model-hook
- Repository: https://github.com/marcosap/form-model-hook
- Homepage: https://github.com/marcosap/form-model-hook#readme
- Issues: https://github.com/marcosap/form-model-hook/issues
- npm.io page: https://npm.io/package/form-model-hook

## Recent versions

- 1.0.9 (latest) — 2022-07-26
- 1.0.8 — 2022-07-26
- 1.0.7 — 2022-07-26
- 1.0.6 — 2022-07-21
- 1.0.5 — 2022-07-20
- 1.0.4 — 2022-07-20
- 1.0.2 — 2022-07-20
- 1.0.1 — 2022-07-20
- 1.0.0 — 2022-07-20

## README

# React form model hook

A very simple hook to abstract common patterns on form data and validation.

Premisses:

 - Have a very simple API
 - Bring the behavior implementation out of the form
 - Be very flexible with validation

Codebox sample:


[![Edit form-model-hook-sample](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/form-model-hook-sample-forked-dvbdrk?fontsize=14&hidenavigation=1&theme=dark)


## Installation


```bash
  yarn add form-model-hook
```
    
## Usage

The `useFormModel` hook, takes the initial data `Object` and a validators `Object` and returns
another `Object` with the utilities that will be used to implements the form behaviour.

The returned `FormModel` object have the following structure:

```javascript
    {
        data,       //the model data
        setField,   //a function to set the fields value: setField('name', value)
        validate,   //a function to trigger a full or field exclusive validation
        isValid,    //a function that returns if the model data is all valid
        pristine,   //a boolean that indicates if the data isn't changed yet
        errors      //a Object with the message errors by field.
    }
```

Each field of the validators Object, needs a corresponding field on the initial data Object, 
in order to known what field needs to be validated by the given validators.

A validator is simply a function that takes a value and return a string with the 
error description to be used. A empty string return means `no error`.


```javascript


...

function required(value) {
  if (value === "") {
    return "This is a required field";
  }

  return "";
}

...
```

Usage example:

```javascript

import useFormModel from 'form-model-hook'

function App() {

    const initialData = {
        name: '',
        email: ''
    }

    const validators = {
        name: [required],
        email: [required, email]
    }

    const model = useFormModel(initialData, validators)

    return <form>

        <Input
          id="name"
          label="Name"
          value={model.data.name}
          onChange={(value) => model.setField("name", value)}
          onBlur={() => model.validate("name")}
          error={model.errors.name}
        />

        <Input
          id="email"
          label="Email"
          value={model.data.email}
          onChange={(value) => model.setField("email", value)}
          error={model.errors.email}
        />

        <button disabled={model.pristine || !model.isValid()}>
            Send
        </button>

      </form>

    ....
}
```

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