useArrayField
Array values, item identifiers, and list operations.
useArrayField
useArrayField({ form, name }) returns a reactive ArrayFieldApi. The array and item types follow the selected schema path. It manages list values and item field identities; it does not create input props for the items.
import { , , } from '@oxform/react';
import { } from 'zod';
function () {
const = ({ : .({ : .(.()) }), : { : ['alpha'] } });
const = ({ , : 'tags' });
return (
<>
{..((, ) => (
< ={} ={} ={`tags.${}`}>
{ => < {....} />}
</>
))}
< ='button' ={() => .('')}>
Add tag
</>
</>
);
}Properties
| Property | Behavior |
|---|---|
options | Current { form, name } binding. |
store | Read-only observable array field store. |
state | Reactive snapshot with id, value, defaultValue, ref, issues, and status. |
ids | Item identifiers in current index order. Empty when the array is absent. Use these identifiers as React keys. |
The API has no props, value, or id shortcut. Read state.value and state.id. Item IDs follow items when inserting, swapping, moving, and removing; update and replace reset affected field state.
Methods
All mutation methods return void and accept FieldChangeOptions as their final argument. They mark the array and ancestors dirty and touched by default. should.dirty: false and should.touch: false preserve existing ancestor status. Except for remove, mutations request change validation when configured, unless disabled.
get()
Returns the current array value. An optional array may return undefined or null as allowed by its schema.
const values = tags.get();append(value, options?) and prepend(value, options?)
Add an item at the end or beginning. An absent array is treated as empty.
tags.append('beta');
tags.prepend('alpha', { should: { validate: false } });insert(index, value, options?)
Inserts an item and shifts later items right. Negative indices become zero. An index past the end pads intervening positions with undefined; choose an index between zero and the length to avoid padding.
tags.insert(1, 'middle');Append, prepend, and insert also accept updater functions typed as receiving an item. The current runtime passes the current whole array to these insertion callbacks. Prefer direct item values for these operations.
swap(from, to, options?)
Exchanges two items and their associated state. Negative indices become zero. Equal normalized indices are a no-op. Use existing indices; positive out-of-range indices are not clamped.
tags.swap(0, 1);move(from, to, options?)
Moves an item while preserving the order of intervening items. Negative indices become zero. Moving to the same index preserves values but still applies normal change status and validation behavior. Use existing indices.
tags.move(0, 2);update(index, valueOrUpdater, options?)
Replaces one item. An updater receives that item's current value. The index is clamped to the existing range; on an empty array it selects position zero. Resets affected item field state and marks the item dirty and touched according to the options.
tags.update(0, 'updated');
tags.update(0, current => current.toUpperCase());remove(index, options?)
Removes one item and shifts later items left, preserving their identities. Negative indices select the first item; an index past the end selects the last. Removing from an empty array leaves it empty. This operation skips validation even when should.validate: true; call form.validate explicitly if needed.
tags.remove(0);
await form.validate('tags', { type: 'change' });replace(valueOrUpdater, options?)
Replaces the full array; an updater receives the current array value. Resets field state for the array and descendants, removes trailing state from a shorter replacement, and applies array dirty/touched flags.
tags.replace(['alpha', 'beta']);
tags.replace(current => current.filter(value => value !== ''));ArrayField
Accepts form, an array name, and static children or a render function receiving the full useArrayField return value. It does not add a DOM wrapper.
import { , } from '@oxform/react';
import { } from 'zod';
function () {
const = ({ : .({ : .(.()) }), : { : [] } });
return (
< ={} ='tags'>
{ => (
< ='button' ={() => .('new')}>
Add tag
</>
)}
</>
);
}Adapter Lifecycle
array['~mount']() returns cleanup. array['~update']({ form, name }) updates the binding. React handles these calls.
Signatures
Prop
Type
Prop
Type
Prop
Type