You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An atom that represents a list of form fields in a form. It manages state for the list, including the name, value, errors, dirty, validation and empty state.
A component that render the individual items of listAtom with render props to render AddButton, RemoveButton and/or Empty slate.
List atoms
listAtom()
An atom that represents a list of form fields in a form. It manages state for the list, including the name, value, errors, dirty, validation and empty state.
exporttypeListAtomConfig<FieldsextendsFormFields,Value>={/** * Optionally provide a name for the field that will be added * prefixed to inner fields * E.g. list name "contacts" and field name "email" * will have scoped name for the 4th item "contacts[3].email" */name?: string;/** * The initial array of values of the list */value: Value[];/** * A function to initialize the fields for each of the initial values. */fields: (value: Value)=>Fields;/** * Error message the listAtom will have, when its items have nested errors. * It will be one of errors returned by the `useFieldErrors()` hook. */invalidItemError?: string;/** * A function that validates the value of the field any time * one of its atoms changes. It must either return an array of * string error messages or undefined. If it returns undefined, * the validation is "skipped" and the current errors in state * are retained. */validate?: (state: {/** * A Jotai getter that can read other atoms */get: Getter;/** * The current value of the field */value: Value;/** * The dirty state of the field */dirty: boolean;/** * The touched state of the field */touched: boolean;/** * The event that caused the validation. Either: * * - `"change"` - The value of the field has changed * - `"touch"` - The field has been touched * - `"blur"` - The field has been blurred * - `"submit"` - The form has been submitted * - `"user"` - A user/developer has triggered the validation */event: ValidateOn;})=>void|string[]|Promise<void|string[]>;};
Returns
An extended FieldAtom:
exporttypeListAtom<FieldsextendsFormFields,Value>=ExtendFieldAtom<Value[],{/** * An atom indicating whether the list is empty. */empty: Atom<boolean>;/** * A splitAtom() instance from jotai/utils. * It handles adding, removing and moving of items in the list. * @internal */_splitList: WritableAtom<PrimitiveAtom<ListItemForm<Fields>>[],[SplitAtomAction<ListItemForm<Fields>>],void>;/** * An atom holding the list of forms of each item. * @internal */_formList: WritableAtom<ListItemForm<Fields>[],[typeofRESET|SetStateAction<ListItemForm<Fields>[]>],void>;/** * An atom holding the fields of the internal formAtom of each item. * @internal */_formFields: Atom<Fields[]>;buildItem(): ListItemForm<Fields>;}>;
A hook that returns a add, remove & move actions, that can be used to interact with the list atom state.
Arguments
Name
Type
Required?
Description
listAtom
ListAtom<Fields extends FormFields, Value>
Yes
The atom that stores the list's state
options
UseAtomOptions
No
Options that are forwarded to the useAtom, useAtomValue, and useSetAtom hooks
Returns
exporttypeUseListActions<FieldsextendsFormFields>={/** * Removes the item from the list. * * @param item - An item from the listAtom's splitList array. */remove: (item: ListItem<Fields>)=>void;/** * Appends a new item to the list by default, when no 'before' position is used. * Optionally the item can be initialized, with the 'fields' argument. * * @param before - An item from the listAtom's splitList array. * @param fields - A custom initialized fieldAtoms matching the Fields shape of the list. */add: (before?: ListItem<Fields>|undefined,fields?: Fields|undefined,)=>void;/** * Moves the item to the end of the list, or where specified when the 'before' is defined. * * @param item - A splitList item to be moved. * @param before - A splitList item before which to place the moved item. */move: (item: ListItem<Fields>,before?: ListItem<Fields>|undefined)=>void;};
A hook that returns the list items ready to be rendred together with the list actions.
Arguments
Name
Type
Required?
Description
listAtom
ListAtom<Fields extends FormFields, Value>
Yes
The atom that stores the list's state
options
UseAtomOptions
No
Options that are forwarded to the useAtom, useAtomValue, and useSetAtom hooks
Returns
exporttypeUseList<FieldsextendsFormFields>=UseListActions<Fields>&{/** * Resolved value from the list.empty atom. */isEmpty: boolean;items: {/** * The item from the internal splitList. */item: ListItem<Fields>;/** * Stable React key prop derived from atom id. */key: string;/** * The form fields of the current item. */fields: Fields;/** * A function to remove the current item from the list. */remove: ()=>void;/** * A helper function to move the item to the previous index in the list. */moveUp: ()=>void;/** * A helper function to move the item to the next index in the list. */moveDown: ()=>void;};};
Your children render prop will receive the following props:
typeListItemProps<FieldsextendsFormFields>={/** * The fields of current item, as returned from the builder function. */fields: Fields;/** * The item from the internal splitList. */item: ListItem<Fields>;/** * The index of the current item. */index: number;/** * Total count of items in the list. */count: number;/** * Append a new item to the end of the list. * When called with current item, it will be prepend with a new item. */add: (before?: ListItem<Fields>)=>void;/** * Removes the current item. */remove: ()=>void;/** * Moves the current item one slot up in the list. * When called for the first item, the action is no-op. */moveUp: ()=>void;/** * Moves the current item one slot down in the list. * When called for the last item, the item moves to the start of the list. */moveDown: ()=>void;/** * A component with an onClick handler bound to remove the current item from the list. */RemoveButton: FunctionComponent;};