ReactForms

The ReactForms component controls all of the state for the form and provides several functions that manipulate this state or perform imperative actions.

Props

Name	Type	Default	Description
id	string	Random UUID	Unique identifier for the form
names	string[]	[]	List of field names that will be included in the form state. Names and default states are populated when Field components mount, however you can use the names array to tell the form about fields that aren't rendered yet, so you can manipulate their state before the Field has mounted for the first time.
initialValues	Partial<Values>	{}	Values that should be populated when the form mounts. Used to determine each fields isDirty state
touchOnChange	boolean	false	Whether each field will update it's touched state when the onChange function is called
touchOnBlur	boolean	true	Whether each field will update it's touched state when the onBlur function is called
validateOnChange	boolean	false	Whether each field will run the validate function when the onChange function is called
validateOnBlur	boolean	true	Whether each field will run the validate function when the onBlur function is called
validate	Validation<T, R> \| { [key: string]: SingleValidation<T, R> } \| CreateValidationRulesArgs	undefined	Configuration describing how to validate each field within the form OR a function that returns an object of field errors
handleSubmit	Submission<Values, Helpers>	undefined	Function that runs when the submitForm function is called and the form has passed validation
render / children	(props: FormPassthroughProps<T, R>) => JSX.Element	undefined	Function that takes the current form state and actions and returns the form components to render

Render prop args

The render prop is passed most of the form context and contains all of the data and actions that a user will need to create their forms.

State

Name	Type	Description
id	string	Unique identifier of the form
names	string[]	List of all of the field names that are within this form
fieldArrayNames	string[]	List of all of the field array names that are within this form
initialValues	Partial<Values>	The initial values passed into the form used to populate the values of the fields on mount
values	Partial<Values>	The values for all of the fields that are managed by this form
touched	BooleanObject	The touched state of all of the fields within this form - whether or not the user has interacted with any given field
errors	FormErrorObject	The error state of all of the fields within this form
nonBlockingError	FormError	An error that doesn't block form submission, but should still be visible to the user
meta	any	Arbitrary state that is passed to some of the callbacks as part of the Helpers
submitCount	number	How many times this form has been submitted (successfully or not)
isDirty	boolean	Whether any of the fields within the form are considered dirty (field value is different from the initialValue)
isValidating	boolean	Whether any of the fields are currently validating their input
isValid	boolean	Whether all of the fields are considered valid (if the form has been submitted, any field with an error is considered invalid, otherwise any field with an error that is also touched and isDirty is considered invalid)
isSubmitting	boolean	Whether or not this form is currently submitting
fieldIsDirty	BooleanObject	The isDirty state for each individual field
fieldIsValidating	BooleanObject	The isValidating state for each individual field
fieldIsValid	BooleanObject	The isValid state for each individual field

Actions

Name	Type	Description
setFieldValue	(name: string, value: any) => void	Imperatively set a value for a specific field
setFieldTouched	(name: string, touched: boolean) => void	Imperatively set the touched state for a specific field
setFieldError	(name: string, error: string \| FormError) => void	Imperatively set an error on a specific field
setServerError	(error: string \| FormError) => void	Imperatively set a nonBlockingError
setMeta	(meta: any) => void	Set any arbitrary meta information about the form
setValues	(values: Partial<T>) => void	Imperatively set values for multiple fields at once
setTouched	(touched: BooleanObject) => void	Imperatively set the touched state for multiple fields at once
setErrors	(errors: FormErrorObject) => void	Imperatively set errors for multiple fields at once
resetField	(name: string, value?: any) => void	Reset a specific field to it's initial state, optionally pass a value to change the initial value
resetForm	(values?: Partial<T>) => void	Reset all fields to their initial state, optionally pass values to change the initial values
validateField	(name: string, value: any) => void	Run validation for a specific field
validateForm	() => void	Run validations for all fields
submitForm	(args?: { shouldReset?: boolean; onValidationFail?: ValidationFailArg; }) => Promise<R> \| R \| boolean \| void	Attempts to submit the form; runs validation and the handleSubmit if it passes