Field Arrays

The FieldArray component simplifies working with arrays of fields as it supports index-based field access (e.g. 'fieldname.0').

To validate the entire array, provide a validate prop to form.FieldArray and place a form.ErrorMessage component below it.

The array is marked as touched when any of its child fields is touched.

1. Basic example

The following example demonstrates a basic usage of the FieldArray component.

import { defineForm } from '@crustack/form'

const form = defineForm<{ fruits: string[] }>()

export function GroceryForm() {
  return (
    <form.Root
      initialValues={{ fruits: ['apple', 'banana'] }}
      onSubmit={() => 'success'}
    >
      {(ctx) => (
        <form.Form>
          <form.FieldArray
            name="fruits"
            // validate the whole field array at once
            validate={(fruits) =>
              fruits.includes('pineapple') && 'You must not include pineapple'
            }
          >
            {ctx.getFieldArrayValue('fruits').map((fruit, index) => (
              <form.Field name={`fruits.${index}`} key={fruit}>
                <form.Control>
                  <input
                    value={ctx.getFieldValue(`fruits.${index}`)}
                    onChange={(e) =>
                      ctx.setFieldValue(`fruits.${index}`, e.target.value)
                    }
                  />
                </form.Control>
              </form.Field>
            ))}

            {/* Display the field array error message */}
            <form.ErrorMessage />
          </form.FieldArray>
        </form.Form>
      )}
    </form.Root>
  )
}

2. With insert / delete

This example demonstrates how to insert and delete items from the array.

import { defineForm } from '@crustack/form'

type FormValues = { items: string[]; newItem: string }

const form = defineForm<FormValues>()

export function GroceryForm() {
  return (
    <form.Root
      initialValues={{ items: ['apples', 'meat'], newItem: '' }}
      onSubmit={() => 'success'}
    >
      {(ctx) => (
        <form.Form>
          <form.FieldArray
            name="items"
            validate={(items) =>
              // validate the entire field array at once
              items.length < 3 && 'You must have at least 3 items'
            }
          >
            {ctx.getFieldArrayValue('items').map((item, index) => (
              <form.Field name={`items.${index}`} key={item}>
                <Input label={item} />

                <button
                  type="button"
                  onClick={() => {
                    // remove the item from the values
                    ctx.setFieldArrayValue('items', (state) => {
                      const items = [...state.items]
                      items.splice(index, 1)
                      return items
                    })
                    // keep the values and touched states in sync
                    ctx.setFieldArrayTouched('items', (touched) => {
                      const touchedItems = [...(touched.items ?? [])]
                      touchedItems.splice(index, 1)
                      return touchedItems
                    })
                  }}
                >
                  Remove item
                </button>
              </form.Field>
            ))}
            {/* The FieldArray's ErrorMessage */}
            <form.ErrorMessage />
          </form.FieldArray>

          <form.Field name="newItem">
            <Input label="New Item" />

            <button
              type="button"
              onClick={() => {
                // add the newItem to the items
                ctx.setFieldArrayValue('items', [
                  ...ctx.getFieldArrayValue('items'),
                  ctx.getFieldValue('newItem'),
                ])
                // clear the newItem field
                ctx.setFieldValue('newItem', '')
              }}
            >
              Add new Item
            </button>
          </form.Field>
        </form.Form>
      )}
    </form.Root>
  )
}

Field Arrays

1. Basic example

2. With insert / delete

On this page