diff --git a/src/content/docs/useform/watch.mdx b/src/content/docs/useform/watch.mdx index 1c7a8672..7dcf93e0 100644 --- a/src/content/docs/useform/watch.mdx +++ b/src/content/docs/useform/watch.mdx @@ -4,46 +4,113 @@ description: Subscribe to input changes sidebar: apiLinks --- -## \ `watch:` (names?: string | string[] | (data, options) => void) => unknown +## \ `watch:` _some overloads_ This method will watch specified inputs and return their values. It is useful to render input value and for determining what to render by condition. -### Props +### Overloads + +This function mainly serves **two purposes**: + +1. Returns and keep sync with fields' values + a. `watch(name: string, defaultValue?): unknown` + b. `watch(names: string[], defaultValue?): {[key:string]: unknown}` + c. `watch(): {[key:string]: unknown}` +2. Start subscribing with given callback function (can be stopped by calling `unsubscribe` function) + a. `watch(callback: (data, { name, type }) => void, defaultValues?): { unsubscribe: () => void }` + +The explanation of each of these four overloads follows below. + +#### 1-a. Watching single field `watch(name: string, defaultValue?: unknown): unknown` + +--- + +Watch and subscribe to a single field used outside of render. + +**Params** + +| Name | Type | Description | +| -------------- | ------------------------------ | ----------------------------------- | +| `name` | `string` | the field name | +| `defaultValue` | `unknown` | _optional_. default value for field | + +**Returns** the single field value. + +```tsx +const name = watch("name") +``` + +#### 1-b. Watching some fields `watch(names: string[], defaultValue?: {[key:string]: unknown}): unknown[]` --- -| Type | Description | -| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | -| string | Watch input value by name (similar to lodash [get](https://lodash.com/docs/4.17.15#get) function) | -| string[] | Watch multiple inputs | -| undefined | Watch all inputs | -| `(data: unknown, { name: string, type: string }) => void` | Watch all inputs and invoke a callback | +Watch and subscribe to an array of fields used outside of render. + +**Params** + +| Name | Type | Description | +| -------------- | ---------------------------------------------- | ------------------------------------- | +| `names` | `string[]` | the field names | +| `defaultValue` | `{[key:string]: unknown}` | _optional_. default values for fields | + +**Returns** an array of field values. + +```tsx +const [name, name1] = watch(["name", "name1"]) +``` -### Return +#### 1-c. Watching the entire form `watch(): {[key:string]: unknown}` --- -| Example | Return | -| ---------------------------------------------------------------- | -------------------------------------------------- | -| `watch('inputName')` | unknown | -| `watch(['inputName1'])` | unknown[] | -| `watch()` | `{[key:string]: unknown}` | -| `watch((data, { name, type }) => console.log(data, name, type))` | `{ unsubscribe: () => void }` | +Watch and subscribe to the entire form update/change based on onChange and re-render at the useForm. - +**Params** None + +**Returns** the entire form values. + +```tsx +const formValues = watch() +``` + +#### 2. Start watching with callback fn `watch(callback: (data, { name, type }) => void, defaultValues?: {[key:string]: unknown}): { unsubscribe: () => void }` + +--- + +Subscribe to field update/change without trigger re-render. + +**Params** + +| Name | Type | Description | +| --------------- | ----------------------------------------------------- | ---------------------------------------------------- | +| `callback` | `(data, { name, type }) => void` | callback function to subscribe to all fields changes | +| `defaultValues` | `{[key:string]: unknown}` | _optional_. defaultValues for the entire form | + +**Returns** object with `unsubscribe` function. + +```tsx +useEffect(() => { + const { unsubscribe } = watch((value) => { + console.log(value) + }) + return () => unsubscribe() +}, [watch]) +``` + +### Rules + +--- - When `defaultValue` is not defined, the first render of `watch` will return `undefined` because it is called before `register`. It's **recommended** to provide `defaultValues` at `useForm` to avoid this behaviour, but you can set the inline `defaultValue` as the second argument. - When both `defaultValue` and `defaultValues` are supplied, `defaultValue` will be returned. - This API will trigger re-render at the root of your app or form, consider using a callback or the [useWatch](/docs/usewatch) api if you are experiencing performance issues. - `watch` result is optimised for render phase instead of `useEffect`'s deps, to detect value update you may want to use an external custom hook for value comparison. - - -**Examples:** +### Examples: --- -**Watch in a Form** +#### Watch in a Form @@ -138,7 +205,7 @@ function App() { -**Watch in Field Array** +#### Watch in Field Array