useForm

This Hook is available since v1.7.0.

A React Hook for managing form state.

  • When used with the native <form />, it operates in uncontrolled mode, meaning changes to the form do not trigger component re-renders. (Ultimate performance)
  • When used with third-party component libraries, it works well in the regular controlled mode, such as with shineout and so on.

Scene

  • Form state management scenario: Manage the state of each form field, achieving updates for the entire form or individual fields
  • Form validation and submission scenario: Implement validation and submission operations for form data
  • Dynamic form scenario: Dynamically add or remove form items to flexibly meet complex form requirements

Demo

Source
Gender:
Color:

Usage

const {
  value,
  setValue,
  setFieldValue
  submit,
  reset,
  submitting,
  initialValue,
  handleChange,
  handleSubmit,
  handleReset,
  checkValidity,
  reportValidity,
  nativeProps,
} = useForm(options)

// Example usage
const form = useForm({
  initialValues: {
    name: 'John Doe',
    email: 'hi@john.doe',
  },
  onSubmit: (form) => {
    console.log(form)
  },
})

// form.nativeProps are used to pass down properties to the native form element
// form.submitting is used to check if the form is currently submitting

// form.submit() is used to submit the form
// form.reset() is used to reset the form
// form.setValue() is used to modify the entire form value
// form.setFieldValue() is used to set a single form field value

// form.checkValidity() validates the form's validity, underlyingly calling the native form's checkValidity method, only valid for native forms
// form.reportValidity() validates and reports the form's validity, underlyingly calling the native form's reportValidity method, only valid for native forms

// When using native form elements in uncontrolled mode, but internally controlling the form's ref
// An internal mechanism ensures that executing `setValue` and `setFieldValue` operations synchronizes with UI state
return (
  <form {...form.nativeProps}>
    <label>Name:<input type="text" name="name" /></label>
    <label>Email:<input type="email" name="email" /></label>
    <button disabled={form.submitting} type="submit">Submit</button>
    <button type="reset">Reset</button>
  </form>
)

// When using a component library, controlled mode, e.g., shineout
return (
  <Form
    value={form.value}
    onChange={form.onChange}
    onSubmit={form.onSubmit}
    onReset={form.onReset}
    defaultValue={form.initialValue}
  >
    <Form.Item label="姓名"><Input type="text" name="name" /></Form.Item>
    <Form.Item label="邮箱"><Input type="email" name="email" /></Form.Item>
    <Form.Submit loading={form.submitting}>提交</Form.Submit>
    <Form.Reset>重置</Form.Reset>
  </Form>
)

Source

Click links below to view source on GitHub.

API

const form = useForm(options)

Options

export interface UseFormOptions<FormState extends object> {
  /**
   * Initial value of the form
   *
   * @defaultValue {}
   */
  initialValue?: FormState
  /**
   * Callback to be called when the form value changes
   *
   * @defaultValue undefined
   */
  onChange?(form: FormState): void
  /**
   * Callback to be called when the form is submitted
   *
   * @defaultValue undefined
   */
  onSubmit?(form: FormState): void
  /**
   * Callback to be called when the form is reset
   *
   * @defaultValue undefined
   */
  onReset?(): void
  /**
   * When use `nativeProps`, whether to prevent default when the form is submitted
   *
   * @defaultValue true
   */
  preventDefaultWhenSubmit?: boolean
  /**
   * Whether to emit extra change event when the form is reset
   *
   * @defaultValue false
   * 
   * @deprecated will be removed in the next major version, please avoid using
   */
  triggerOnChangeWhenReset?: boolean
}

Returns

export type UseFormReturnsNativeProps = {
  /**
   * Ref of the form element
   */
  ref: RefObject<HTMLFormElement | null>
  /**
   * Callback to be called when the form value changes
   */
  onChange(e: ChangeEvent<HTMLFormElement>): void
  /**
   * Callback to be called when the form is submitted
   */
  onSubmit(e: ChangeEvent<HTMLFormElement>): void
  /**
   * Callback to be called when the form is reset
   */
  onReset(e: ChangeEvent<HTMLFormElement>): void
}

export interface UseFormReturns<FormState extends object> {
  /**
   * Whether the form is submitting
   */
  submitting: boolean
  /**
   * Set the new value of the whole form
   */
  setValue: ReactSetState<FormState>
  /**
   * Set a field value of the form
   */
  setFieldValue<Name extends keyof FormState>(name: Name, value: FormState[Name]): void
  /**
   * Reset the form to its initial value
   */
  reset(): void
  /**
   * Submit the form
   */
  submit(): void
  /**
   * Current value of the form
   */
  value: FormState
  /**
   * Initial value of the form
   */
  initialValue: FormState
  /**
   * handle form value changes
   */
  handleChange(form: FormState): void
  /**
   * handle form submit
   */
  handleSubmit(form: FormState): void
  /**
   * handle form reset
   */
  handleReset(): void
  /**
   * Check and report the native form validity, only valid for native form
   */
  reportValidity(): boolean
  /**
   * Check the native form validity, only valid for native form
   */
  checkValidity(): boolean
  /**
   * Native form related props
   */
  nativeProps: UseFormReturnsNativeProps
}