Dynamic form rows
Add a blank row to a repeatable form section.
Conform · Module
intent.insert
The insert intent adds a new item to an array field without submitting the form. It can append or place the item at an index, initialize it directly, or populate it from another validated field.
How it works
The insert intent adds an item to an array field without submitting the form. Provide the array field name, optionally choose its index, and supply a default value; if the index is omitted, the item is appended.
Syntax
insert(options): voidParameters
| Name | Type | Description |
|---|---|---|
name | string | Name of the array field receiving the item. |
index | number | Optional position at which to insert the item; omission appends it. |
defaultValue | unknown | Optional initial value for the new item. |
from | string | Optional source field whose value is validated and inserted. |
onInvalid | 'revert' | Optional invalid-operation behavior; currently supports 'revert'. |
Returns
void
Key points
- The intent operates on array fields and adds one new element.
- The name option identifies the array that receives the inserted item.
- Use index to place the item at a chosen position.
- defaultValue establishes the inserted element’s starting value.
- from lets the insertion obtain its value from another field.
- onInvalid currently accepts revert to undo an insertion rejected by array validation.
Common mistakes
- Leaving out index appends the item rather than inserting it at a specific position.
- Using from or onInvalid depends on synchronous error availability.
- When from supplies an invalid value, no item is inserted and the source field receives the error.
Example: Insert an array item imperatively
const intent = useIntent(form.ref);
intent.insert({
name: fields.tasks.name,
index: 1,
defaultValue: { title: '' },
});This inserts a new item into the tasks array at index 1 with an initial value.
When to use it
Tag entry
Turn an input value into a newly added tag.
Ordered lists
Place a new record at a user-selected position.
Interview questions
QHow do you insert an item into an array field?
Call the dispatcher’s insert method with the array field’s name. The index is optional; without it, the new item is appended.
Follow-up: How can an item be populated from another field? Use from; Conform validates that source value, inserts it only when valid, and clears the source field afterward.
QHow do you give the inserted item an initial value?
Pass defaultValue in the insert options. This provides the initial value for the new array item.
Follow-up: What happens when the source value supplied through from fails validation? The operation is cancelled and the error is displayed on the source field.
QHow can insertion respond to an array validation error?
Set onInvalid to 'revert' when an array-level validation error should cancel the operation, such as when the array exceeds its maximum length. This option requires synchronous error availability.
Follow-up: Why might an insert be cancelled even when the item itself is valid? Array-level validation can reject the updated list, and the revert behavior cancels the insertion.
Related
useIntentuseFormform.insertIntent buttonNested object and Array