fix(form-core): bump _arrayVersion when async defaultValues update array fields

.changeset/nine-beds-shout.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/form-core': patch
+---
+
+Fix array async default values not updating

packages/form-core/src/FormApi.ts

@@ -1512,6 +1512,17 @@ export class FormApi<
       )
     })
 
+    if (shouldUpdateValues) {
+      const helper = metaHelper(this)
+      for (const fieldKey of Object.keys(
+        this.fieldInfo,
+      ) as DeepKeys<TFormData>[]) {
+        if (Array.isArray(this.getFieldValue(fieldKey))) {
+          helper.bumpArrayVersion(fieldKey)
+        }
+      }
+    }
+
     formEventClient.emit('form-api', {
       id: this._formId,
       state: this.store.state,

packages/react-form/tests/useField.test.tsx

@@ -1526,6 +1526,44 @@ describe('useField', () => {
     expect(getByTestId('item-1')).toHaveTextContent('John')
   })
 
+  it('should rerender array field when async defaultValues resolve', async () => {
+    // Regression test for https://github.com/TanStack/form/issues/2178
+    // When async defaultValues arrive after initial render, array fields in
+    // mode="array" must re-render because _arrayVersion is used as the
+    // reactivity signal (not value length).
+    type Person = { name: string }
+    type FormData = { people: Person[] }
+
+    function Comp({ defaultValues }: { defaultValues?: FormData }) {
+      const form = useForm({ defaultValues })
+
+      return (
+        <form.Field name="people" mode="array">
+          {(field) => {
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            const val = field.state.value ?? []
+            return (
+              <ol data-testid="list">
+                {val.map((person, i) => (
+                  <li key={i} data-testid={`item-${i}`}>
+                    {person.name}
+                  </li>
+                ))}
+              </ol>
+            )
+          }}
+        </form.Field>
+      )
+    }
+
+    const { getByTestId, rerender } = render(<Comp />)
+    expect(getByTestId('list').children).toHaveLength(0)
+
+    rerender(<Comp defaultValues={{ people: [{ name: 'Alice' }] }} />)
+    await waitFor(() => expect(getByTestId('list').children).toHaveLength(1))
+    expect(getByTestId('item-0')).toHaveTextContent('Alice')
+  })
+
   it('should handle defaultValue without setstate-in-render error', async () => {
     // Spy on console.error before rendering
     const consoleErrorSpy = vi.spyOn(console, 'error')