npm install --save recoil-form recoil
// or
yarn add recoil-form recoil
This project is currently in "Work in progress" status
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.
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.
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 pairssetValues: ({ [name: string]: any }) => void
– set form values by passing values object (similar toinitialValues
).setValues: (name: key, value: any, ...) => void
– set form values by passing name-value pairsresetForm: () => void
– reset form to initial state (clear form values, errors and touched states)
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.
Field name. The name is used as main field identifier and as a key in values
object in onSubmit
form handler.
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.
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.
React component which is used to render the field. Default is 'input'
.
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.
Renders default input field (except cases when type
is "checkbox"
, "radio"
or "file"
which are described below)
name: string
– the name of the fielddefaultValue?: string
- field's initial value- all other props except
value
are passed down to underlyinginput
component.value
is just ignored.
Renders default checkbox field.
name: string
– the name of the fieldvalue?: any
- value used when checkbox checked. Default istrue
uncheckedValue?: any
- value used when checkbox unchecked. Default isundefined
defaultChecked?: boolean
- if current checkbox checked or not. IfdefaultChecked={true}
then initial value for the field set inForm.initialValues
is always overridden withvalue
.- all other props are passed down to underlying
input
component.
Renders default radio button.
name: string
– the name of the fieldvalue: any
- value used when radio button checked.defaultChecked?: boolean
- if current radio button checked or not. IfdefaultChecked={true}
then initial value for the field set inForm.initialValues
is overridden withvalue
. Keep in mind the case, when more than one radio button hasdefaultChecked={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.
Not supported yet. WIP.
Not supported yet. WIP.
Not supported yet. WIP.
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.
The name of the field to which current error message is related.
React component which is used to render the error message. Default is 'small'
.
Not ready yet. WIP
Not ready yet. WIP
useFormState
is a custom hook to retrieve current form state. Either 'ready'
or 'submitting'
is returned from this hook
useFormState(): 'ready' | 'submitting'
useFormValues
is a custom hook to retrieve current form values.
useFormValues(): any
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.
useField<TValue = any>(name: string, initialValue?: string): [FieldInputProps<TValue>, 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
.
name: string
- The name of the fieldvalue: TValue
- The field's valueonBlur: (event: React.FocusEvent) => void
- A blur event handleronChange: (event: React.ChangeEvent<any>) => void
- A change event handler
WIP
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 valuesetTouched(value: boolean): void
- A function to change the field's touched statussetError(value: any): void
- A function to change the field's error value
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.
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
is a custom React hook that will allow you to get error updater function without subscription to field's error state.
useSetFieldValue
is a custom React hook that will allow you to get value updater function without subscription to field's value state.
MIT