--- title: setValue seoTitle: "setValue: Update React Form Values" description: Dynamically update a registered field's value. metaDescription: Dynamically update a registered field's value with options to trigger validation, mark the field dirty, or set it as touched. sidebar: apiLinks --- ## \ `setValue:` [UseFormSetValue](/ts#UseFormSetValue) This function allows you to dynamically set the value of a registered field and provides options to validate and update the form state. At the same time, it attempts to avoid unnecessary re-renders. ### Props --- | Name | | Description | | ---------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name`
string | | Target a single field or field array by name. | | `value`
unknown | | The value for the field. This argument is required and cannot be `undefined`. | | `options` | `shouldValidate`
boolean | | | | `shouldDirty`
boolean | | | | `shouldTouch`
boolean | Whether to set the input itself to be touched. | | | `delayError`
boolean | Opt-in flag that delays the display of the resulting validation error, using the delay (in milliseconds) configured via [`useForm({ delayError })`](/docs/useform#delayError). Only takes effect when `shouldValidate` is also set to `true`. | - By default, `setValue` only updates the value and notifies [`watch`](/docs/useform/watch), [`useWatch`](/docs/usewatch) and [`subscribe`](/docs/useform/subscribe). It does **not** validate the field (even after the form has been submitted) or mark it as dirty or touched. Pass the options you need: ```javascript setValue("firstName", "Bill", { shouldValidate: true, // update errors and isValid shouldDirty: true, // update dirtyFields and isDirty shouldTouch: true, // update touchedFields }) ``` - `shouldDirty` only guarantees that the target field is marked in `dirtyFields` immediately. Because `isDirty` always compares current values against `defaultValues`, a later update to _any_ field can trigger a `dirtyFields` recompute that also surfaces other fields whose value already differs from their default — including ones last written with `shouldDirty: false`. - You can use methods such as [replace](/docs/usefieldarray#return) or [update](/docs/usefieldarray#return) for a field array; however, they will cause the component to unmount and remount for the targeted field array. ```javascript 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's recommended to target the field's name rather than make the second argument a nested object. ```javascript 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 finds the input and updates it ``` - It's recommended to register the input's name before invoking `setValue`. To update the entire `FieldArray`, make sure the `useFieldArray` hook is being executed first. **Important:** Prefer `replace` from `useFieldArray` for updating an entire field array — it's the more explicit, purpose-built API, and this `setValue` usage may become discouraged in a future version. ```javascript // you can update an entire Field Array, setValue("fieldArray", [{ test: "1" }, { test: "2" }]) // ⚠️ works, but prefer replace() from useFieldArray // you can use `setValue` on an unregistered input setValue("notRegisteredInput", "value") // ✅ prefer it to be registered // the following will implicitly register a single input (without register being invoked) setValue("resultSingleNestedField", { test: "1", test2: "2" }) // ⚠️ works, but registers a field you never called register() on — prefer registering it explicitly // With registered inputs, `setValue` will update both inputs correctly. register("notRegisteredInput.test") register("notRegisteredInput.test2") setValue("notRegisteredInput", { test: "1", test2: "2" }) // ✅ sugar syntax to setValue twice ``` ### Examples --- **Basic** ```javascript sandbox="https://codesandbox.io/s/react-hook-form-v7-ts-setvalue-8z9hx" import { useForm } from "react-hook-form" const App = () => { const { register, setValue } = useForm({ defaultValues: { firstName: "", }, }) return (
) } ``` **Delay Error** ```javascript // the actual delay (in ms) is configured once at the form level const { setValue } = useForm({ delayError: 500 }) setValue("firstName", "Bill", { delayError: true, // opt in to the 500ms delay configured above shouldValidate: true, }) ``` **Dependent Fields** ```tsx sandbox="https://codesandbox.io/s/dependent-field-dwin1" import { useEffect } from "react" import { useForm } from "react-hook-form" type FormValues = { a: string b: string c: string } export default function App() { const { watch, register, handleSubmit, setValue, formState } = useForm({ defaultValues: { a: "", b: "", c: "", }, }) const onSubmit = (data: FormValues) => console.log(data) const [a, b] = watch(["a", "b"]) useEffect(() => { if (formState.touchedFields.a && formState.touchedFields.b && a && b) { setValue("c", `${a} ${b}`) } }, [setValue, a, b, formState]) return (
) } ``` ### Video --- ### Tips --- - When a value comes from the user through a custom widget, such as a map picker or a rich-text editor, pass `{ shouldDirty: true, shouldTouch: true, shouldValidate: true }`. The field then behaves the same as a native input that the user typed in. - To update several fields at once, use [`setValues`](/docs/useform/setvalues). It updates them with a single re-render, while calling `setValue` many times can cause more renders. - Do not call `setValue` during render. Call it in an event handler or an effect. ### Troubleshooting --- #### `isDirty` and errors don't change after `setValue` By default, `setValue` only updates the value. It does not validate the field or mark it as dirty or touched. Pass the options you need: ```javascript setValue("email", value, { shouldValidate: true, shouldDirty: true, shouldTouch: true, }) ```