# react-form-state-context

> Provide form state via a React Context

Latest version **2.4.1** (published 2023-09-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-form-state-context
pnpm add react-form-state-context
yarn add react-form-state-context
bun add react-form-state-context
```

## Health

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

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.4.1 |
| Published | 2023-09-26 |
| First published | 2020-11-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 17.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Maarten Nieber |
| Maintainers | mnieber |

## Links

- npm: https://www.npmjs.com/package/react-form-state-context
- Repository: https://github.com/mnieber/react-form-state-context
- Homepage: https://github.com/mnieber/react-form-state-context#readme
- Issues: https://github.com/mnieber/react-form-state-context/issues
- npm.io page: https://npm.io/package/react-form-state-context

## Recent versions

- 2.4.1 (latest) — 2023-09-26
- 2.4.0 — 2023-08-10
- 2.3.1 — 2023-06-16
- 2.3.0 — 2022-11-07
- 2.1.2 — 2022-09-12
- 2.1.1 — 2022-09-05
- 2.1.0 — 2022-06-14
- 1.2.0 — 2021-04-08
- 1.1.0 — 2021-02-25
- 1.0.15 — 2020-11-24

## README

# react-form-state-context

The react-form-state-context library is a React hooks based solution for processing forms. The main idea is that the form state is stored in a single object which is made available to all the elements in the form via a React context.

```
<FormStateProvider
  initialValues={getInitialValues()}
  initialErrors={getInitialErrors()}
  handleValidate={myHandleValidate}
  handleSubmit={myHandleSubmit}
  handleCancel={myHandleCancel}
>
  <NameField>
  <NameFieldError>
  <AddressField>
  <AddressFieldError>
  <SubmitButton>
</FormStateProvider>
```

The form components obtain access to the form state using `const formState = useFormStateContext();`.
They can use `formState` as follows:

- `formState.getValue(<field name>)` is called to get a current form value.
- `formState.setValue(<field name>, <field value>)` is called to update a form value.
- `formState.getError(<field name>)` is used to get the current error for a form field.
- `formState.validate()` is called to validate all form fields (see the explanation of `handleValidate` below).
- `formState.submit()` is called to submit the form contents (see the explanation of `handleSubmit` below).
- `formState.cancel()` is called to cancel the form (see the explanation of `handleCancel` below).
- `formState.reset(initialValues, initialErrors)` resets the form.

## Important note: the form values and errors are mutable

When you call `formState.setValue('myField', 'myNewValue')` then this does two things:

- It changes the form (immediately). If you call `formState.getValue('myField')` right after then it will return `myNewValue`.
- It triggers a re-render of all components that use the related `FormStateContext`.

The same is true when calling `formState.setError` and `formState.getError`.

## Field names

The `formState` functions will only allow field-names that were listed in the `initialValues` property. Use `null` to initialize values for which you don't have (or don't want to use) a regular initial value.

## Form resets

If you change the `initialValues` or `initialErrors` property value then `formState.reset` is called automatically. The JSON.stringify function is used to determine if the values or errors have changed, so ensure that the `initialValues` or `initialErrors` are stringify-able (if they are not, then you may be able to fix this by adding a `toJSON` function to these objects).

## Validation

The `handleValidate` function is executed when you call `formState.validate()`. In `handleValidate` you can set form field errors, as shown in the example code below:

```
const handleValidate = ({ values, getValue, setError }) => {
  if (!getValue("name")) {
    setError("name", "Please enter your name");
  }
};
```

You don't need to clear previous errors in `handleValidate` because `formState.validate()` takes care of this. Note that it's usually not necessary to call `formState.validate()` in your code because `formState.submit()` calls it automatically.

## Submitting

The `handleSubmit` function is executed when you call `formState.submit()`. It takes the object with all form values as its argument. An example handleSubmit function is:

```
const handleSubmit = (values) => {
  // do something with the form contents...
  console.log(values.name);
};
```

When you call `formState.submit()` this will first call `formState.validate()` and only execute the `handleSubmit` function if there are no form errors.

## Dirty and pristine fields

This library provides no api for finding out which form fields have been touched. However, for fields that were initialized
to `null` (using the `initialValues` property) this is easy to find out, as long as the form components do not assign
`null` to form values.

## The createFormFieldProps() function

This is a helper function that connects an `<input>` element with a form state. An example usage is:

```
const addressInputProps = createFormFieldProps({
  formState: formState,
  fieldName: 'address',
  fieldType: 'text',
  onChange: myOnChange,
  controlled: false,
});

const addressInput = <input {...addressInputProps}/>

```

The output of `createFormFieldProps` is a set of properties that is passed to the <input> element.
In the given example:

- the `name` property of the <input> element will be 'address'
- the `defaultValue` property of the <input> element will be `formState.getValue('address')`
- the `onChange` property of the <input> element will be connected to `myOnChange`
- the form field will not be controlled

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