[{"data":1,"prerenderedAt":504},["ShallowReactive",2],{"content-\u002Fdocs\u002Fwriting-and-mutating\u002Ffield-arrays":3},{"id":4,"title":5,"body":6,"description":483,"extension":484,"meta":485,"metaRows":486,"navigation":253,"path":499,"seo":500,"source":501,"stem":502,"__hash__":503},"docs\u002Fdocs\u002Fwriting-and-mutating\u002Ffield-arrays.md","Field-array mutations",{"type":7,"value":8,"toc":475},"minimark",[9,13,20,23,26,31,36,44,170,174,299,306,310,313,347,350,357,361,380,399,403,417,421,471],[10,11,5],"h1",{"id":12},"field-array-mutations",[14,15,16],"blockquote",{},[17,18,19],"p",{},"Seven shape-changing helpers, typed against every array path in your schema. Stable per-item identity across moves, removes, and swaps.",[21,22],"docs-meta-table",{},[17,24,25],{},"Use the row arrows and per-row × button to move and remove items; the buttons below dispatch every helper against the array. Watch the readout: the order, count, and contents reflect each call. Stable keys mean per-item validation state, dirty bits, and DOM focus survive shape changes; reordering doesn't reset what the user typed.",[27,28],"docs-demo",{"label":29,"slug":30},"Field Arrays Demo","field-arrays",[32,33,35],"h2",{"id":34},"the-seven-helpers","The seven helpers",[17,37,38,39,43],{},"Each helper is typed against the form's ",[40,41,42],"code",{},"ArrayPath\u003CForm>"," set; TypeScript autocompletes only the paths that actually point at an array. The value-shape generic narrows on the inferred element type.",[45,46,47,63],"table",{},[48,49,50],"thead",{},[51,52,53,57,60],"tr",{},[54,55,56],"th",{},"Helper",[54,58,59],{},"Signature",[54,61,62],{},"What it does",[64,65,66,80,93,106,119,132,153],"tbody",{},[51,67,68,74,77],{},[69,70,71],"td",{},[40,72,73],{},"append(path, value)",[69,75,76],{},"adds at the end",[69,78,79],{},"Appends one item to the array.",[51,81,82,87,90],{},[69,83,84],{},[40,85,86],{},"prepend(path, value)",[69,88,89],{},"adds at index 0",[69,91,92],{},"Adds one item to the front; shifts the rest right.",[51,94,95,100,103],{},[69,96,97],{},[40,98,99],{},"insert(path, index, value)",[69,101,102],{},"adds at index",[69,104,105],{},"Inserts one item; shifts subsequent items right.",[51,107,108,113,116],{},[69,109,110],{},[40,111,112],{},"remove(path, index)",[69,114,115],{},"drops at index",[69,117,118],{},"Removes one item; shifts subsequent items left.",[51,120,121,126,129],{},[69,122,123],{},[40,124,125],{},"swap(path, a, b)",[69,127,128],{},"swaps two indices",[69,130,131],{},"Exchanges the items at the two indices.",[51,133,134,139,142],{},[69,135,136],{},[40,137,138],{},"move(path, from, to)",[69,140,141],{},"moves an item",[69,143,144,145,148,149,152],{},"Removes from ",[40,146,147],{},"from"," and re-inserts at ",[40,150,151],{},"to"," in one step.",[51,154,155,160,163],{},[69,156,157],{},[40,158,159],{},"replace(path, index, value)",[69,161,162],{},"replaces at index",[69,164,165,166,169],{},"Overwrites the item at ",[40,167,168],{},"index"," without changing length.",[32,171,173],{"id":172},"reading-the-path","Reading the path",[175,176,181],"pre",{"className":177,"code":178,"language":179,"meta":180,"style":180},"language-ts shiki shiki-themes github-light github-dark","const form = useForm({\n  schema: z.object({\n    checkpoints: z.array(z.string()),\n  }),\n})\n\nform.append('checkpoints', 'New checkpoint')\nform.remove('checkpoints', 2)\n","ts","",[40,182,183,207,218,236,242,248,255,280],{"__ignoreMap":180},[184,185,188,192,196,199,203],"span",{"class":186,"line":187},"line",1,[184,189,191],{"class":190},"szBVR","const",[184,193,195],{"class":194},"sj4cs"," form",[184,197,198],{"class":190}," =",[184,200,202],{"class":201},"sScJk"," useForm",[184,204,206],{"class":205},"sVt8B","({\n",[184,208,210,213,216],{"class":186,"line":209},2,[184,211,212],{"class":205},"  schema: z.",[184,214,215],{"class":201},"object",[184,217,206],{"class":205},[184,219,221,224,227,230,233],{"class":186,"line":220},3,[184,222,223],{"class":205},"    checkpoints: z.",[184,225,226],{"class":201},"array",[184,228,229],{"class":205},"(z.",[184,231,232],{"class":201},"string",[184,234,235],{"class":205},"()),\n",[184,237,239],{"class":186,"line":238},4,[184,240,241],{"class":205},"  }),\n",[184,243,245],{"class":186,"line":244},5,[184,246,247],{"class":205},"})\n",[184,249,251],{"class":186,"line":250},6,[184,252,254],{"emptyLinePlaceholder":253},true,"\n",[184,256,258,261,264,267,271,274,277],{"class":186,"line":257},7,[184,259,260],{"class":205},"form.",[184,262,263],{"class":201},"append",[184,265,266],{"class":205},"(",[184,268,270],{"class":269},"sZZnC","'checkpoints'",[184,272,273],{"class":205},", ",[184,275,276],{"class":269},"'New checkpoint'",[184,278,279],{"class":205},")\n",[184,281,283,285,288,290,292,294,297],{"class":186,"line":282},8,[184,284,260],{"class":205},[184,286,287],{"class":201},"remove",[184,289,266],{"class":205},[184,291,270],{"class":269},[184,293,273],{"class":205},[184,295,296],{"class":194},"2",[184,298,279],{"class":205},[17,300,301,302,305],{},"The path string autocompletes to every array path in the schema. Nested arrays work the same way: ",[40,303,304],{},"register('teams.0.players')"," for an inner array, and the helpers take the same form.",[32,307,309],{"id":308},"stable-per-item-identity","Stable per-item identity",[17,311,312],{},"Every helper preserves the existing items' reactive identity, and an item's full state travels with it to its new index:",[314,315,316,322,338],"ul",{},[317,318,319,321],"li",{},[40,320,263],{}," leaves indices 0..n unchanged.",[317,323,324,273,327,273,330,333,334,337],{},[40,325,326],{},"prepend",[40,328,329],{},"insert",[40,331,332],{},"swap",", and ",[40,335,336],{},"move"," carry the moved item's value, its original baseline, its dirty and touched state, any error you set on it, its blank display, and its bound DOM element to the new index. Nothing bleeds onto the item that shifts into the vacated slot.",[317,339,340,342,343,346],{},[40,341,287],{}," drops the removed item's state; ",[40,344,345],{},"replace"," starts the incoming item fresh.",[17,348,349],{},"Practical consequence: a user typing in row 3, hitting \"Move up\", finishes typing in row 2 without losing focus or having the entered text reset. A row already marked dirty stays dirty at its new index, and the row that shifts into the old slot keeps its own clean state. Attaform tracks the item, not the slot.",[17,351,352,353,356],{},"Because each item carries its own baseline, Attaform still reads a structural change as a change: a reorder, insert, or removal leaves ",[40,354,355],{},"form.meta.dirty"," true even when every surviving item matches its own baseline.",[32,358,360],{"id":359},"validation-per-item","Validation per item",[17,362,363,364,367,368,371,372,375,376,379],{},"Per-item validation tracks the item, not the slot. An error you set with ",[40,365,366],{},"form.setFieldErrors"," on ",[40,369,370],{},"checkpoints.0"," follows the item through a ",[40,373,374],{},"move(0, 4)"," to ",[40,377,378],{},"checkpoints.4",". Schema verdicts recompute from the live value after each shape change, so a still-invalid item shows its error at its new index, and a removed item's verdict clears at once instead of lingering on whatever shifts into the slot.",[17,381,382,383,386,387,390,391,394,395,398],{},"For array-level refinements (",[40,384,385],{},"z.array(...).min(3)"," or ",[40,388,389],{},".refine(arr => arr.length > 0)","), the error lands at the array path itself, not at any slot. Read it via ",[40,392,393],{},"form.errors('checkpoints')"," (or ",[40,396,397],{},"form.fields('checkpoints').firstError",").",[32,400,402],{"id":401},"reset-behavior","Reset behavior",[17,404,405,408,409,412,413,416],{},[40,406,407],{},"reset()"," restores the array's default: same length, same item values, every item back to its pre-edit state. ",[40,410,411],{},"clear('checkpoints')"," writes ",[40,414,415],{},"[]",". No special \"reset the array's helpers\", same pipeline as the rest of the writes.",[32,418,420],{"id":419},"where-to-next","Where to next",[314,422,423,441,451,464],{},[317,424,425,432,433,436,437,440],{},[426,427,429],"a",{"href":428},"\u002Fdocs\u002Freading-the-form\u002Flist",[40,430,431],{},"form.list",": iterate the array as one FieldState per element, keyed by ",[40,434,435],{},"key"," so a ",[40,438,439],{},"v-for"," survives every reorder.",[317,442,443,450],{},[426,444,446,449],{"href":445},"\u002Fdocs\u002Fwriting-and-mutating\u002Fset-value",[40,447,448],{},"setValue"," patterns",": when you need to write the whole array, not mutate one slot.",[317,452,453,463],{},[426,454,456,459,460],{"href":455},"\u002Fdocs\u002Fwriting-and-mutating\u002Freset",[40,457,458],{},"reset"," & ",[40,461,462],{},"resetField",": restore the array to its baseline.",[317,465,466,470],{},[426,467,469],{"href":468},"\u002Fdocs\u002Fvalidation\u002Fshowing-errors","Display state and showing errors",": array-level error display.",[472,473,474],"style",{},"html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":180,"searchDepth":209,"depth":209,"links":476},[477,478,479,480,481,482],{"id":34,"depth":209,"text":35},{"id":172,"depth":209,"text":173},{"id":308,"depth":209,"text":309},{"id":359,"depth":209,"text":360},{"id":401,"depth":209,"text":402},{"id":419,"depth":209,"text":420},"Seven helpers (append, prepend, insert, remove, swap, move, replace) typed against every ArrayPath in your schema. Stable per-item validation and dirty tracking across every shape change.","md",{},[487,490,493,496],{"label":488,"value":489},"Category","Return methods",{"label":491,"value":492},"Helpers","append · prepend · insert · remove · swap · move · replace",{"label":494,"value":495,"kind":40},"Type","typed against ArrayPath\u003CForm>",{"label":497,"value":498},"Stable keys","Yes, per-item identity preserved","\u002Fdocs\u002Fwriting-and-mutating\u002Ffield-arrays",{"title":5,"description":483},null,"docs\u002Fwriting-and-mutating\u002Ffield-arrays","gBvtkl9_QlQZs7Vvr4fWI9fHhHlSWqxf4WSi3g93MIE",1780949759966]