useArrayField#
useArrayField is the hook for array field components. Under the hood, it combines RHF's useFieldArray with the same field metadata layer as useField — giving array components access to both mutation methods and resolved field props in one place.
const { label, errorMessage, items, renderItems, append, ... } = useArrayField()#Field props
The same field props as useField are available directly, scoped to the array field itself — not individual items:
| Prop | Description | Notes |
|---|---|---|
label | Translated label | Resolved from field config through i18n pipeline |
description | Translated helper text | Resolved from field config through i18n pipeline |
errorMessage | Array-level validation error | e.g. from rules.minLength or rules.required — not item errors |
required | Whether the array is required | Derived from rules.required |
disabled | Whether the array is disabled | Resolved for UI logic; does not by itself remove the array from submit payload |
visible | Whether the array should render | When false, the array field unmounts; see conditional rendering |
#Array state
| Prop | Description | Notes |
|---|---|---|
items | Current list of array items | Alias of fields from RHF's useFieldArray — use item.id as React key |
renderItem(field, index) | Render a single item | Scoped automatically to the correct namespace (e.g. addresses.0) |
renderItems() | Render all items | Shorthand for items.map(renderItem) |
#Array methods
RHF's useFieldArray methods, forwarded as-is:
| Method | Description |
|---|---|
append(value) | Add item at the end |
prepend(value) | Add item at the beginning |
insert(index, value) | Add item at a specific position |
remove(index?) | Remove item by index, or all items if omitted |
update(index, value) | Replace item at index |
move(from, to) | Move item to a new position |
swap(a, b) | Swap two items |
replace(values) | Replace the entire list |
Convenience helpers added by BlueForm:
| Helper | Description | Notes |
|---|---|---|
push(value) | Add item at the end | Alias of append |
pop() | Remove the last item | No-op when array is empty |
clear() | Remove all items | Equivalent to remove() with no index |
duplicate(index) | Append a copy of the item at index | Uses current form values — reflects user edits. No-op when index does not exist |
idAt(index) | Stable key for the item | Use as React key — falls back to index if RHF id is unavailable |
errorAt(index) | Validation error subtree for item at index | Useful for highlighting collapsed items with errors |
#Complete example
addresses: {
type: "array",
label: "Addresses",
rules: {
minLength: { value: 2, message: "At least 2 addresses required" },
},
props: {
config: defineConfig<Address>({
street: { type: "text", label: "Street" },
city: { type: "text", label: "City" },
country: { type: "text", label: "Country" },
}),
},
render: () => {
const { items, renderItems, append, duplicate, pop, clear, label, errorMessage } = useArrayField()
return (
<fieldset>
<legend>{label}</legend>
{renderItems()}
<div>
<button
type="button"
onClick={() => append({ street: "", city: "", country: "" })}
>
Add
</button>
<button
type="button"
disabled={!items.length}
onClick={() => duplicate(items.length - 1)}
>
Duplicate last
</button>
<button
type="button"
disabled={!items.length}
onClick={pop}
>
Remove last
</button>
<button
type="button"
disabled={!items.length}
onClick={clear}
>
Clear all
</button>
</div>
{errorMessage && <div>{errorMessage}</div>}
</fieldset>
)
},
}