setValue: (name: string, value: unknown, config?: Object) => void

This function allows you to dynamically set the value of a registered field and have the options to validate and update the form state. At the same time, it tries to avoid unnecessary rerender.

Props

Name		Type	Description
`name`		`string`	Target a single field by name. When used with field array. You can use methods such as `replace` or `update` for field array, however, they will cause the component to unmount and remount for the targeted field array. `const { update } = useFieldArray({ name: 'array' }); // unmount fields and remount with updated value update(0, { test: '1', test1: '2' }) // will directly update input value setValue('array.0.test1', '1'); setValue('array.0.test2', '2');` It will not create a new field when targeting a non-existing field. `const { replace } = useFieldArray({ name: 'test' }) // ❌ doesn't create new input setValue('test.101.data') // ✅ work on refresh entire field array replace([{data: 'test'}])`
`value`		`unknown`	The value for the field. This argument is required and can not be `undefined`.
`options`	`shouldValidate`	`boolean`	Whether to compute if your input is valid or not (subscribed to `errors`). Whether to compute if your entire form is valid or not (subscribed to `isValid`). This option will update `touchedFields` at the specified field level not the entire form touched fields. `setValue('name', 'value', { shouldValidate: true })`
	`shouldDirty`	`boolean`	Whether to compute if your input is dirty or not against your defaultValues (subscribed to `dirtyFields`). Whether to compute if your entire form is dirty or not against your defaultValues (subscribed to `isDirty`). This option will update `dirtyFields` at the specified field level not the entire form dirty fields. `setValue('name', 'value', { shouldDirty: true })`
	`shouldTouch`	`boolean`	Whether to set the input itself to be touched. `setValue('name', 'value', { shouldTouch: true })`

Rules

Only the following conditions will trigger a re-render:
- When an error is triggered or corrected by a value update
- When setValue cause state update, such as dirty and touched.

It's recommended to target the field's name rather than make the second argument a nested object.

setValue('yourDetails.firstName', 'value'); // ✅ performant
setValue('yourDetails', { firstName: 'value' }); // less performant

register('nestedValue', { value: { test: 'data' } }); // register a nested value input
setValue('nestedValue.test', 'updatedData'); // ❌ failed to find the relevant field
setValue('nestedValue', { test: 'updatedData' } ); // ✅ setValue find input and update

It's recommended to register the input's name before invoking setValue. To update the entire Field Array, make sure the useFieldArray hook is being executed first.

Important: use replace from useFieldArray instead, update entire field array with setValue will be removed in the next major version.

// you can update an entire Field Array,
setValue('fieldArray', [{ test: '1' }, { test: '2' }]); // ✅

// you can setValue to a unregistered input
setValue('notRegisteredInput', 'value'); // ✅ prefer to be registered

// the following will register a single input (without register invoked)
setValue('resultSingleNestedField', { test: '1', test2: '2' }); // 🤔

// with registered inputs, the setValue will update both inputs correctly.
register('notRegisteredInput.test', '1')
register('notRegisteredInput.test2', '2')
setValue('notRegisteredInput', { test: '1', test2: '2' }); // ✅ sugar syntax to setValue twice

Examples

CodeSandbox ^JS

import { useForm } from "react-hook-form";

const App = () => {
  const { register, setValue } = useForm();
  
  return (
    <form>
      <input {...register("firstName")} />
      <button type="button" onClick={() => setValue("firstName", "Bill")}>
        setValue
      </button>
      <button
        type="button"
        onClick={() =>
          setValue("lastName", "firstName", {
            shouldValidate: true,
            shouldDirty: true
          })
        }
      >
        setValue options
      </button>
    </form>
  );
};
import { useForm } from "react-hook-form";

const App = () => {
  const { register, setValue } = useForm({
    firstName: ''
  });

  return (
    <form>
      <input {...register("firstName", { required: true })} />
      <button onClick={() => setValue("firstName", "Bill")}>
        setValue
      </button>
      <button
        onClick={() =>
          setValue("firstName", "Luo", {
            shouldValidate: true,
            shouldDirty: true
          })
        }
      >
        setValue options
      </button>
    </form>
  );
};
import React from "react";
import { useForm } from "react-hook-form";

type FormValues = {
  string: string;
  number: number;
  object: {
    number: number;
    boolean: boolean;
  };
  array: {
    string: string;
    boolean: boolean;
  }[];
};

export default function App() {
  const { setValue } = useForm<FormValues>();
  
  setValue("string", "test");
  // function setValue<"string", string>(name: "string", value: string, shouldValidate?: boolean | undefined): void
  setValue("number", 1);
  // function setValue<"number", number>(name: "number", value: number, shouldValidate?: boolean | undefined): void
  setValue("number", "error");
  
  return <form />;
}

Video

The following video tutorial demonstrates setValue API in detail.

Thank you for your support

If you find React Hook Form to be useful in your project, please consider to star and support it.