fix(form-core): handle null field defaults

.changeset/null-field-default-value.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/form-core': patch
+---
+
+Treat field-level `defaultValue: null` as a valid default value instead of falling back to the form-level default when resolving `isDefaultValue` and in `resetField`.

packages/form-core/src/FormApi.ts

@@ -1233,11 +1233,13 @@ export class FormApi<
           // As primitives, we don't need to aggressively persist the same referential value for performance reasons
           const isFieldValid = !isNonEmptyArray(fieldErrors)
           const isFieldPristine = !currBaseMeta.isDirty
+          const fieldDefault =
+            this.getFieldInfo(fieldName).instance?.options.defaultValue
           const isDefaultValue = evaluate(
             curFieldVal,
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            this.getFieldInfo(fieldName)?.instance?.options.defaultValue ??
-              getBy(this.options.defaultValues, fieldName),
+            fieldDefault !== undefined
+              ? fieldDefault
+              : getBy(this.options.defaultValues, fieldName),
           )
 
           if (
@@ -2940,7 +2942,8 @@ export class FormApi<
       const fieldDefault =
         this.getFieldInfo(field).instance?.options.defaultValue
       const formDefault = getBy(this.options.defaultValues, field)
-      const targetValue = fieldDefault ?? formDefault
+      const targetValue =
+        fieldDefault !== undefined ? fieldDefault : formDefault
 
       return {
         ...prev,

packages/form-core/tests/FieldApi.spec.ts

@@ -132,6 +132,42 @@ describe('field api', () => {
     expect(field.getMeta().isDefaultValue).toBe(true)
   })
 
+  it('should treat field-level defaultValue of null as default when form default is non-null', () => {
+    const form = new FormApi({
+      defaultValues: {
+        name: 'test' as string | null,
+      },
+    })
+    form.mount()
+
+    const field = new FieldApi({
+      form,
+      name: 'name',
+      defaultValue: null,
+    })
+    field.mount()
+
+    expect(field.getValue()).toBe(null)
+    expect(field.getMeta().isDefaultValue).toBe(true)
+
+    field.setValue('other')
+    expect(field.getMeta().isDefaultValue).toBe(false)
+
+    field.setValue(null)
+    expect(field.getMeta().isDefaultValue).toBe(true)
+
+    form.resetField('name')
+    expect(field.getValue()).toBe(null)
+    expect(field.getMeta().isDefaultValue).toBe(true)
+
+    field.setValue('other')
+    expect(field.getMeta().isDefaultValue).toBe(false)
+
+    form.reset()
+    expect(field.getValue()).toBe(null)
+    expect(field.getMeta().isDefaultValue).toBe(true)
+  })
+
   it('should be false when value is undefined and a default value is specified in form-level only', () => {
     const form = new FormApi({
       defaultValues: {