Repository files navigation

A type-safe approach to managing complex form state in React.

This library provides integration with@stackup/validate to handle validation. However, it should be pretty easy to integrate whatever validation library you prefer.

You should also checkout@stackup/inputs, which includes some ready-made form fields.

importReactfrom"react";import{useForm,useField}from"@stackup/form";constForm=()=>{constform=useForm({initialValue:{email:"",name:""}});constvalidate=useValidation(form,value=>{if(value.email){return{valid:true, value};}else{return{valid:false,error:{email:"is required"}};}});constsubmit=useSubmit(validate,value=>{console.log(value);});return(<formonSubmit={submit}><Inputtype="email"label="Email"field={useField(form,"email")}/><Inputtype="text"label="Name"field={useField(form,"name")}/><buttontype="submit">Save</button></form>);};constInput=({  label,field:{ id, value, error, touched, setValue, setTouched},  ...props})=>(<div><labelhtmlFor={id}>{label}</label><input{...props}id={id}value={value}onBlur={useCallback(()=>setTouched(true),[])}onChange={useCallback(e=>setValue(e.target.value),[setValue])}/>{touched&&error&&<p>{error}</p>}</div>);

• useForm
• useField
• useValidation
• useValidate
• useSubmit
• useReset
• useFieldItem
• usePushItem
• useInsertItem
• useRemoveItem
• useIdentifier
• Form
• FormField
• ValidateFn
• Submit
• Submission
• Reset
• UseFormOptions
• UseValidationOptions

Create a new form. A form requires an initial value, a function to validate,and a submit handler.

A form behaves just like any other field, but with some extra properties formanaging submission.

The initial value for the form can be literally anything! Usually, it's anobject, but it could be any type of value.

• optionsUseFormOptions<Value>

Form values can be primitive

constform=useForm({initialValue:""});

But usually, they'll contain an object

constform=useForm({initialValue:{email:"",name:""}});

ReturnsForm<Value>

Create a field for a given property.

• fieldFormField<Value>
• nameName

constform=useForm({initialValue:{email:"",profile:{name:""}}}});constemail=useField(form,"email");constprofile=useField(form,"profile");constname=useField(profile,"name");

ReturnsFormField<any>

Use a plain ol' function for validation.

This hook can also be used to incorporate your favorite validation library.

• formForm<Value, Value>
• fnValidateFn<Value, Result>
• optsUseValidationOptions (optional, default{})

constvalidation=useValidation(form,value=>{if(!value.email){return{valid:false,error:{email:"can't be blank"}};}return{valid:true, value};});

ReturnsForm<Value, Result>

Add validation to the form using@stackup/validate.

• formForm<Value, Value>
• validatorValidator<(Value | any), Result>
• optsUseValidationOptions?

constvalidator=schema({email:assert(isString).then(refute(isBlank))});constvalidate=useValidate(form,validator);

ReturnsForm<Value, Result>

Create a submit handler for the form.

• formForm<Value, Result>
• fnSubmitFn<Result>
• optsValidateOptions (optional, default{touch:true})

Sumbitting a form

constform=useForm({initialValue:"foo"});constsubmit=useSubmit(form,console.log);

Sumbitting with validation

constform=useForm({initialValue:"foo"});constvalidate=useValidate(form,myValidator);constsubmit=useSubmit(validate,console.log);

ReturnsSubmit

Create a reset handler for the form.

• formForm<Value, Result>

constform=useForm({initialValue:"foo"});constreset=useReset(form);

ReturnsReset

Create a field for a specific index in an array.

This hook is intended for use in building forms with "Add another" functionality.

• fieldFormField<Array<Value>>
• indexnumber

constform=useForm({initialValue:{pets:[{name:""}]}});constpets=useField(form,"pets");constpet=useFieldItem(pets,0);constname=useField(pet,"name");

ReturnsFormField<Value>

Adds a new value to the end to an array of values.

This can be used to create a form with repeating fields.

• fieldFormField<Array<Value>>
• valueValue

constpets=useField(form,"pets");constpet=useFieldItem(pets,0);constaddPet=usePushItem(pets,{name:""});

Adds a new value at a specific position to an array of values.

This can be used to create a form with repeating fields.

• fieldFormField<Array<Value>>
• indexnumber
• valueValue

constpets=useField(form,"pets");constpet=useFieldItem(pets,0);constinsert=useInsertItem(pets,0,{name:""});

Removes a value at the given index from array of values.

This can be used to create a form with repeating fields.

• fieldFormField<Array<Value>>
• indexnumber

constpets=useField(form,"pets");constpet=useFieldItem(pets,0);constremovePet=useRemoveItem(pets,0);

Creates a unique identifier that will remain consistent across re-renders.

This hook does not currently support SSR.

• idstring?

Returnsstring

Extends FormField<Value>

The value returned byuseForm.

The initial values for the form.

Type: Value

The initial errors on the fields.

Type: FormError<Value>

The initially touched fields.

Type: FormTouched<Value>

Indicate that the form is validating

Type: SetState<boolean>

Indicate that the form is validating

Type: SetState<boolean>

Update the form's submission status

Type: SetState<Submission>

Reset the state of the form

Type: function (opts: ResetOptions<Value>): void

Run validation

Type: function (opts: ValidateOptions):Promise<ValidationResult<Value, Result>>

The primary form data structure.

A unique ID for this form field. This can be used to associate fields with a label.

Type:string

The name or array index that was given touseField oruseFieldItem.

Type: (string |number)

The current value of the field.

Type: Value

An error or errors that are associated with this field or it's children.

Type: FormError<Value>

Indicates that this field or it's children have been modified by the user.

Type: FormTouched<Value>

Indicates that validation is currently being run

Type:boolean

Indicates that the form is currently being submitted

Type:boolean

Keeps track of the form's submission status

Type:Submission

Change the value. Just like withsetState, you can pass a callbackto this function to get the current value and update it.

Type: SetState<Value>

Update the error.

Type: SetState<FormError<Value>>

Indicate that this field has been touched. This is usually called inonBlur.

Type: SetState<FormTouched<Value>>

A function used for validation. This function must indicate whetheror not the form is valid.

Theerror property can be used to set errors on the form.

Thevalue property can be used to transform the form's values beforevalidation.

Type: function (value: Value): (ValidationResult<Value, Result> | PromiseLike<ValidationResult<Value, Result>>)

Submits the form.

Type: function (event: FormEvent<HTMLFormElement>):Promise<void>

Keeps track of submissions.

The number of times the form has been submitted

Type:number

If the submission flow throws an error, it will appear here.

Type:Error

Resets the form.

Type: function (event: FormEvent<HTMLFormElement>):Promise<void>

The options that can be passed touseForm.

Customize the base ID for all fields.

Type:string

The initial values for the form.

Type: Value

The initial errors on the fields.

Type: FormError<Value>

The initially touched fields.

Type: FormTouched<Value>

Configures when validation runs.

Enables validation whenever values change.

Type:boolean

Enables validation whenever a field is touched.

Type:boolean