Add rows to a repeatable form section
A form contains a repeatable list such as tasks, contacts, or line items.
Conform · Pipe
form.insert
form.insert creates an intent for adding an item to an array field. Use its generated button props for a declarative control, or invoke the intent directly for imperative behavior.
How it works
form.insert is the declarative intent helper for adding an item to an array field. Configure a button with its getButtonProps method and pass the array field's name; clicking the button submits the intent so the form can process the insertion.
Syntax
form.insert.getButtonProps({ name: fields.tasks.name })Parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the array field into which the new item is inserted. |
Returns
An intent helper exposed by useForm; its getButtonProps method returns props for a declarative insert button.
Key points
- Use getButtonProps on form.insert to create a declarative insert button.
- Pass the target array field's name through the name option.
- The insert intent can also be invoked imperatively with the array field name.
Common mistakes
- The helper relies on a reserved button name and serialized intent value, so avoid replacing the generated button props.
Example: Insert an item into an array field
const [form, fields] = useForm();
return (
<Form method="post" {...getFormProps(form)}>
<ul>
{fields.tasks.getFieldList().map((task) => (
<li key={task.key}>
<input {...getInputProps(task, { type: "text" })} />
</li>
))}
</ul>
<button {...form.insert.getButtonProps({ name: fields.tasks.name })}>
Add task
</button>
</Form>
);The button submits an insert intent for the tasks array, allowing Conform to add an item while preserving progressive enhancement.
When to use it
Trigger insertion imperatively
A custom event handler must request insertion instead of relying on a button's default interaction.
Interview questions
QWhat does form.insert do, and how is it used declaratively?
form.insert creates an insertion intent for an array field. The declarative form is form.insert.getButtonProps({ name: fields.tasks.name }), which supplies the button props needed to request the insertion.
Follow-up: How can the same action be triggered imperatively? Use form.insert({ name: fields.tasks.name }) from an event handler.
QWhich argument is required for the insert helper?
The name option identifies the array field receiving the new item. The button example passes fields.tasks.name, connecting the intent to the tasks list.
Follow-up: What should be rendered for existing array entries? Obtain the entries through the parent metadata's getFieldList() method.
QHow does Conform represent insert actions?
Conform uses submission intent for form controls, including insert, remove, and reorder operations. The generated button props encode that intent so the action works through the form submission model.
Follow-up: Which related helper handles deletion? form.remove provides the corresponding removal intent.
Related
form.removeform.reordergetFieldListuseFormIntent button