houseform
Version:
Simple to use React forms, where your validation and UI code live together in harmony.
64 lines (56 loc) • 10.4 kB
Markdown
# Array Field
An `ArrayField` is a wrapper used to handle arrays of form items. An example `ArrayField` usage is:
```jsx
<FieldArray name={"numbers"} initialValue={[1]}>
{({ add, value }) => (
<>
{value.map((num) => (
<p key={num}>{num}</p>
))}
<button onClick={() => add(1)}>Set value</button>
</>
)}
</FieldArray>
```
## Array Field Props
The `ArrayField` component takes the following props:
| Property | Type | Description |
|---------------------| -------------------------------------------------------------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name` | `string` | The name of the array field within the form. |
| `initialValue` | `T[]` | The initial value of the field array. |
| `resetWithValue` | `T[]` | The value to which a field array should be reset upon calling the `reset()` method. |
| `preserveValue` | `boolean` | Preserve the field's values when unmount. |
| `listenTo` | `string[]` | A list of form field names to listen to. When a listened field updates it's value, it will trigger the relevant `onChangeValidation` change detection. Useful when making one field depend on the validation of another. |
| `children` | `(props: FieldArrayInstance<T>) => JSX.Element` | Passed [`FieldArrayInstance`](#interface-fieldarrayinstance), expected to return a JSX element. |
| `onChangeValidate` | `() => Promise<boolean>` or [`ZodType`](https://github.com/colinhacks/zod) | The validation logic for when the user has changed the field value. Either a Zod type or Promise. If resolved, no error is passed. If rejected, rejection string is set as an error. |
| `onMountValidate` | `() => Promise<boolean>` or [`ZodType`](https://github.com/colinhacks/zod) | The validation logic for when the component is mounted. Either a Zod type or Promise. If resolved, no error is passed. If rejected, rejection string is set as an error. |
| `onSubmitValidate` | `() => Promise<boolean>` or [`ZodType`](https://github.com/colinhacks/zod) | The validation logic for when the user has submitted the form. Either a Zod type or Promise. If resolved, no error is passed. If rejected, rejection string is set as an error. |
| `onChangeHint` | `() => Promise<boolean>` or [`ZodType`](https://github.com/colinhacks/zod) | The soft validation logic for when the user has changed the field value. Either a Zod type or Promise. If resolved, no hint is passed. If rejected, rejection string is set as a hint. |
| `onMountHint` | `() => Promise<boolean>` or [`ZodType`](https://github.com/colinhacks/zod) | The soft validation logic for when the component is mounted. Either a Zod type or Promise. If resolved, no hint is passed. If rejected, rejection string is set as a hint. |
| `onSubmitHint` | `() => Promise<boolean>` or [`ZodType`](https://github.com/colinhacks/zod) | The soft validation logic for when the user has submitted the form. Either a Zod type or Promise. If resolved, no hint is passed. If rejected, rejection string is set as a hint. |
| `onSubmitTransform` | `(value: T) => any` or [`ZodType`](https://github.com/colinhacks/zod) | The transform function for when the user has submitted the form. Either a Zod transform or Function. The form will receive the transformed value instead if set. |
| `memoChild` | `any[]` | An array of items passed to the inner `useMemo` [which helps prevent re-renders on the field array.](/guides/performance-optimizations) |
### _Interface_ `FieldArrayInstance`
| Property | Type | Description |
|----------------|-----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| `value` | `T` | `T` is the type of the Field that's passed to the `<Field<T>>` component. |
| `setValue` | `(val: T) => void` | A function useful to change the value of a field |
| `setValues` | `(val: T[]) => void` | A function useful to change the value of the form array. |
| `errors` | `string[]` | The list of errors currently applied to the field. |
| `setErrors` | `(errors: string[]) => void` | A way to set the errors present on the field. |
| `hints` | `string[]` | The list of hints currently applied to the field. |
| `setHints` | `(hints: string[]) => void` | A way to set the hints present on the field. |
| `isValid` | `boolean` | A helper property to check if `errors` is an empty array. |
| `isValidating` | `boolean` | A helper property to check if the field is running a validation. |
| `isTouched` | `boolean` | A boolean to say if the field has been focused and blurred, regardless of user input. |
| `setIsTouched` | `(val: boolean) => void` | |
| `isDirty` | `boolean` | A boolean to say if the field has had any kind of user input. |
| `setIsDirty` | `(val: boolean) => void` | |
| `props` | [`ArrayFieldProps`](#array-field-props) | The properties originally passed to a field from the component. |
| `add` | `(val: T) => void` | A helper utility to add an item to the form array. |
| `remove` | `(index: number) => void` | A helper utility to remove an item via an index from the form array. |
| `insert` | `(index: number, val: T) => void` | A helper utility to insert an item at the index to the form array. |
| `move` | `(from: number, to: number) => void` | A helper utility to move an item from one index to another in the form array. |
| `replace` | `(index: number, val: T) => void` | A helper utility to replace an item at an index on the form array. |
| `swap` | `(indexA: number, indexB: number) => void` | A helper utility to swap two items on the form array. |
| `validate` | `(rule: 'onChangeValidate' \| 'onSubmitValidate' \| 'onMountValidate' \| 'onBlurValidate') => void` | A method of running manual change detection on a field arrary. |