Skip to content

docs: document exact ancestor-path matching since 7.81.0 #1231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bluebill1049 merged 1 commit into from
Aug 29, 2026
Merged

docs: document exact ancestor-path matching since 7.81.0 #1231

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions src/content/docs/usecontroller.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,15 @@ This custom hook powers [`Controller`](/docs/usecontroller/controller). Addition

The following table contains information about the arguments for `useController`.

| Name | Type | Required | Description |
| ------------------ | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | <TypeText>[FieldPath](/ts#FieldPath)</TypeText> | ✓ | Unique name of your input. Reactive — the controller re-subscribes when this prop changes, allowing dynamic field name switching. |
| `control` | <TypeText>[Control](/ts#Control)</TypeText> | | [`control`](/docs/useform/control) object provided by invoking `useForm`. Optional when using `FormProvider`. |
| `rules` | <TypeText>Object</TypeText> | | Validation rules in the same format for `register`, which includes: `required`, `min`, `max`, `minLength`, `maxLength`, `pattern`, `validate`.<br/><br/>`rules={{ required: true }}` |
| `shouldUnregister` | <TypeText>boolean = false</TypeText> | | Input will be unregistered after unmount and defaultValues will be removed as well. **Note:** this prop should be avoided when using with `useFieldArray` as `unregister` function gets called after input unmount/remount and reorder. |
| `disabled` | <TypeText>boolean = false</TypeText> | | <Since version="7.46.0" /> `disabled` prop will be returned from `field` prop. Controlled input will be disabled and its value will be omitted from the submission data. |
| `defaultValue` | <TypeText>unknown</TypeText> | | **Important:** Cannot apply `undefined` to `defaultValue` or `defaultValues` at `useForm`.<ul><li>You need to either set `defaultValue` at the field-level or `useForm`'s `defaultValues`. `undefined` is not a valid value. If you used `defaultValues` at `useForm`, skip using this prop.</li><li>If your form will invoke `reset` with default values, you will need to provide `useForm` with `defaultValues`.</li><li>If `field.value` is `undefined` on first render, the input starts out uncontrolled and React will warn when it later becomes controlled — always set `defaultValue`/`defaultValues` to avoid this.</li></ul> |
| `exact` | <TypeText>boolean = true</TypeText> | | <Since version="7.68.0" /> This prop will enable an exact match for input name subscriptions, default to true. **Note:** this differs from [`useWatch`](/docs/usewatch) and [`useFormState`](/docs/useformstate), which both default `exact` to `false`. |
| Name | Type | Required | Description |
| ------------------ | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | <TypeText>[FieldPath](/ts#FieldPath)</TypeText> | ✓ | Unique name of your input. Reactive — the controller re-subscribes when this prop changes, allowing dynamic field name switching. |
| `control` | <TypeText>[Control](/ts#Control)</TypeText> | | [`control`](/docs/useform/control) object provided by invoking `useForm`. Optional when using `FormProvider`. |
| `rules` | <TypeText>Object</TypeText> | | Validation rules in the same format for `register`, which includes: `required`, `min`, `max`, `minLength`, `maxLength`, `pattern`, `validate`.<br/><br/>`rules={{ required: true }}` |
| `shouldUnregister` | <TypeText>boolean = false</TypeText> | | Input will be unregistered after unmount and defaultValues will be removed as well. **Note:** this prop should be avoided when using with `useFieldArray` as `unregister` function gets called after input unmount/remount and reorder. |
| `disabled` | <TypeText>boolean = false</TypeText> | | <Since version="7.46.0" /> `disabled` prop will be returned from `field` prop. Controlled input will be disabled and its value will be omitted from the submission data. |
| `defaultValue` | <TypeText>unknown</TypeText> | | **Important:** Cannot apply `undefined` to `defaultValue` or `defaultValues` at `useForm`.<ul><li>You need to either set `defaultValue` at the field-level or `useForm`'s `defaultValues`. `undefined` is not a valid value. If you used `defaultValues` at `useForm`, skip using this prop.</li><li>If your form will invoke `reset` with default values, you will need to provide `useForm` with `defaultValues`.</li><li>If `field.value` is `undefined` on first render, the input starts out uncontrolled and React will warn when it later becomes controlled — always set `defaultValue`/`defaultValues` to avoid this.</li></ul> |
| `exact` | <TypeText>boolean = true</TypeText> | | <Since version="7.68.0" /> This prop will enable an exact match for input name subscriptions, default to true. <Since version="7.81.0" /> With `exact: true`, the field is also updated when one of its ancestor paths is set (for example, a field named `"users.0.name"` reflects `setValue("users.0", { name: "Jane" })`), but not when a nested child path of its value changes (for example, `setValue("users.0.name", "Jane")` does not update a field named `"users.0"`). Pass `exact: false` to also receive nested updates. **Note:** this differs from [`useWatch`](/docs/usewatch) and [`useFormState`](/docs/useformstate), which both default `exact` to `false`. |

### Return

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/usecontroller/controller.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ The following table contains information about the arguments for `Controller`.
| `shouldUnregister` | <TypeText>boolean = false</TypeText> | | Input will be unregistered after unmount and defaultValues will be removed as well.<br/><br/>**Note:** this prop should be avoided when using with `useFieldArray` as `unregister` function gets called after input unmount/remount and reorder. |
| `disabled` | <TypeText>boolean = false</TypeText> | | <Since version="7.46.0" /> `disabled` prop will be returned from `field` prop. Controlled input will be disabled and its value will be omitted from the submission data. |
| `defaultValue` | <TypeText>unknown</TypeText> | | **Important:** Cannot apply `undefined` to `defaultValue` or `defaultValues` at `useForm`. <ul><li>You need to either set `defaultValue` at the field level or `useForm`'s `defaultValues`. If you used <code>defaultValues</code> at <code>useForm</code>, skip using this prop.</li><li>If your form will invoke `reset` with default values, you will need to provide `useForm` with `defaultValues`.</li><li>Calling `onChange` with `undefined` is not valid. You should use `null` or the empty string as your default/cleared value instead.</li><li>If `field.value` is `undefined` on first render, the input starts out uncontrolled and React will warn when it later becomes controlled — always set `defaultValue`/`defaultValues` to avoid this.</li></ul> |
| `exact` | <TypeText>boolean = true</TypeText> | | <Since version="7.68.0" /> This prop will enable an exact match for input name subscriptions, default to true. |
| `exact` | <TypeText>boolean = true</TypeText> | | <Since version="7.68.0" /> This prop will enable an exact match for input name subscriptions, default to true. <Since version="7.81.0" /> With `exact: true`, the field is also updated when one of its ancestor paths is set, but not when a nested child path of its value changes. See [`useController`](/docs/usecontroller) for details. |

### Return

Expand Down
Loading