useForm

useForm is the base hook containing all @per-form/react logic.

Parameters

useForm take only one parameter that is an object with the following shape:

Property	Type	Default	Description
defaultValues	Record<string, unknown>		Form default values (see default values guide for more information)
filterLocalErrors	boolean	true	Filter local errors from the global form errors (see local fields guide for more information)
focusOnError	boolean	true	Focus the first field error or not
form	HTMLFormElement	null	Form ref
messages	Record<string, string>		Custom messages (see messages guide for more information)
mode	'all' | 'blur' | 'change' | 'submit'	'submit'	Validation strategy (see mode guide for more information)
onBlurOptOut	string[] | string		Opt-out for native onBlur event
onChangeOptOut	string[] | string		Opt-out for native onChange event (see controlled components guide for more information)
onReset	IResetHandler		Reset callback
onSubmit	ISubmitHandler		Submit callback
onSubmitError	ISubmitErrorHandler		Submit error callback (only when useNativeValidation=false)
revalidateMode	'blur' | 'change' | 'submit'	'submit'	Re-validation strategy (see mode guide for more information)
transformers	Record<string, (value: unknown) => unknown>		Transformers for type casting see type casting guide for more information)
useNativeValidation	boolean		Use native browser validation or use error state
validators	Record<string, IValidator | IValidatorObject>		Custom field validators (see validation guide for more information)

See here for the types.

Returns

useForm return an object with the following shape:

Property	Type	Description
errors	IError	Form errors (see errors guide for more information)
form	RefObject<HTMLFormElement>	Form ref
formProps	IFormProps	Form props to add on your form component
messages	Record<string, string>	Given custom messages
mode	'all' | 'blur' | 'change' | 'submit'	Chosen Validation strategy
onChange	IOnChangeHandler	Change handler (see type casting guide and controlled components guide for more information)
onError	IOnErrorHandler	Manual error handler (see controlled components guide for more information)
onReset	IOnResetHandler	Reset handler (see reset guide for more information)
onSubmit	IOnSubmitHandler	Submit handler (see submit guide for more information)
register	IRegister	Internal usage
reset	IFormReset	Manual reset function
revalidateMode	'blur' | 'change' | 'submit'	Chosen re-validation strategy
states	IFormStates	Form states (warning: these are not react states)
subscribe	ISubscribe	Function to subscribe to state change (see the form state guide for more information)
unregister	IUnregister	Internal usage
useNativeValidation	boolean	Choice for native validation or not
validate	IFormValidate	Manual validate function
watch	IWatch	Manual watch function (see watch guide for more information)

See here for the types.

Usage

Just add {...formProps} to your <form> and you are ready:

0

useNativeValidation

mode

revalidateMode

values

errors

import type { FormEvent } from 'react';
import type { IProps } from '../types';
import { type IFormValues, useForm } from '@per-form/react';

export default function Demo(props: IProps) {
  function handleSubmit(_e: FormEvent<HTMLFormElement>, values: IFormValues) {
    console.log(values);
  }

  const { errors, formProps } = useForm({
    ...props,
    onSubmit: handleSubmit,
  });

  return (
    <form {...formProps}>
      <input name="text" required />
      {errors.all.text && <div className="error">{errors.all.text}</div>}
      <button type="submit">Submit</button>
    </form>
  );
}