Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/serverscom/recoil-form

Blazing fast React forms build on top of Recoil
https://github.com/serverscom/recoil-form

Last synced: about 1 month ago
JSON representation

Blazing fast React forms build on top of Recoil

Awesome Lists containing this project

README 

        
# `recoil-form`: blazing fast React forms build on top of Recoil



## Installation

```

npm install --save recoil-form recoil

// or

yarn add recoil-form recoil

```



## Work in progress



This project is currently in "Work in progress" status



## API and Usage



### `Form` component



Use `Form` component as a main container for your form. This component creates a special form context, so all other components may only be used inside the `Form` component.



#### Props



##### `initialValues: { [name: string]: any | Promise }`



Initial field values of the form. If promise is passed as an initial value of the field, then field is suspended until promise is resolved and resolved promise value will be used as a field value. See `Field` for more details.



##### `onSubmit: (values, { setErrors, setValues, resetForm }) => void | Promise`



Your form submission handler. It is passed your forms values and special methods to change form state:



* `setErrors: ({ [name: string]: any }) => void` – set form errors by passing errors object. Key is used as field name and value is used as an error value.

* `setErrors: (name: key, value: any, ...) => void` – set form errors by passing name-value pairs

* `setValues: ({ [name: string]: any }) => void` – set form values by passing values object (similar to `initialValues`).

* `setValues: (name: key, value: any, ...) => void` – set form values by passing name-value pairs

* `resetForm: () => void` – reset form to initial state (clear form values, errors and touched states)



### `Field` component



Use `Field` component to add a new field to your form. `Field` component may represent default `input` or `select` components or any other custom component.



#### Props



##### `name: string`



Field name. The name is used as main field identifier and as a key in `values` object in `onSubmit` form handler.



##### `type?: string`



Field type. Used only if `as` property is not set. `type` defines which default underlying component will be used to represent the field. See supported types below.



##### `value?: any`



Field value. Used for `checkbox` and `radio` components. We do not use `event.target.value` internally, so you may use the value of any type. See more details below.



##### `as: ElementType`



React component which is used to render the field. Default is `'input'`.



##### `fallback: ReactNode`



If you pass a `Promise` as a field value or initial value, this promise will be used with `React.Suspense`. Component will be suspended with `fallback` until promise is resolved. Once resolved, promise value will be used as field value or initial value.



#### Supported types



##### Default behaviour (`as="input"` or `as={undefined}` or missed `as` prop)



Renders default input field (except cases when `type` is `"checkbox"`, `"radio"` or `"file"` which are described below)



* `name: string` – the name of the field

* `defaultValue?: string` - field's initial value

* all other props except `value` are passed down to underlying `input` component. `value` is just ignored.



##### `type="checkbox"` (works only with `as="input"` or `as={undefined}` or missed `as` prop)



Renders default checkbox field.



* `name: string` – the name of the field

* `value?: any` - value used when checkbox checked. Default is `true`

* `uncheckedValue?: any` - value used when checkbox unchecked. Default is `undefined`

* `defaultChecked?: boolean` - if current checkbox checked or not. If `defaultChecked={true}` then initial value for the field set in `Form.initialValues` is always overridden with `value`.

* all other props are passed down to underlying `input` component.



##### `type="radio"` (works only with `as="input"` or `as={undefined}` or missed `as` prop)



Renders default radio button.



* `name: string` – the name of the field

* `value: any` - value used when radio button checked.

* `defaultChecked?: boolean` - if current radio button checked or not. If `defaultChecked={true}` then initial value for the field set in `Form.initialValues` is overridden with `value`. Keep in mind the case, when more than one radio button has `defaultChecked={true}`. In such case last rendered radio button will be checked and it's value will be used as an initial value for the field.

* all other props are passed down to underlying `input` component.



##### `type="file"`



Not supported yet. WIP.



##### `as="select"`



Not supported yet. WIP.



##### Custom components via `as={MyCustomComponent}`



Not supported yet. WIP.



### `ErrorMessage` component



Use `ErrorMessage` component to render error message related to the field. Error message is only shown for `touched` fields which has an truthy error value.



#### Props



##### `name: string`



The name of the field to which current error message is related.



##### `as: ElementType`



React component which is used to render the error message. Default is `'small'`.



### `FieldArray` component



Not ready yet. WIP



### `useForm` hook



Not ready yet. WIP



### `useFormState` hook



`useFormState` is a custom hook to retrieve current form state. Either `'ready'` or `'submitting'` is returned from this hook



#### Reference



`useFormState(): 'ready' | 'submitting'`



### `useFormValues` hook



`useFormValues` is a custom hook to retrieve current form values.



#### Reference



`useFormValues(): any`



### `useField` hook



`useField` is a custom React hook that will help you hook up inputs to `recoil-form`. You can use it to build your own custom input or input-related component.



#### Reference



##### `useField(name: string, initialValue?: string): [FieldInputProps, FieldMetaProps, FieldHelperProps]`



A custom React Hook that returns a 3-tuple (an array with three elements) containing `FieldProps`, `FieldMetaProps` and `FieldHelperProps`. It accepts a string of a field `name` and optional `initialValue`.



##### `FieldInputProps`



* `name: string` - The name of the field

* `value: TValue` - The field's value

* `onBlur: (event: React.FocusEvent) => void` - A blur event handler

* `onChange: (event: React.ChangeEvent) => void` - A change event handler



##### `FieldMetaProps`



WIP



##### `FieldHelperProps`



An object that contains helper functions which you can use to imperatively change the value, error value or touched status for the field in question. This is useful for components which need to change a field's status directly, without triggering change or blur events.



* `setValue(value: any): void` - A function to change the field's value

* `setTouched(value: boolean): void` - A function to change the field's touched status

* `setError(value: any): void` - A function to change the field's error value



### `useErrorMessage` / `useFieldError` hook

`useErrorMessage` (or it's alias `useFieldError`) is a custom react hook that will allow you to get the field error. Your component will be automatically re-rendered when error is changed.



#### Reference



##### `useFieldError(name: string): TValue | null`



### `useFieldValue` hook



`useFieldValue` is a custom react hook that will allow you to get the current field value. Your component will be automatically re-rendered when value is changed.



### `useSetFieldError` hook



`useSetFieldError` is a custom React hook that will allow you to get error updater function without subscription to field's error state.



### `useSetFieldValue` hook



`useSetFieldValue` is a custom React hook that will allow you to get value updater function without subscription to field's value state.



## License



MIT