fix: yield to paint before submit validation so isSubmitting UI shows

.changeset/is-submitting-paint.md

@@ -0,0 +1,12 @@
+---
+'@tanstack/form-core': patch
+'@tanstack/react-form': patch
+'@tanstack/preact-form': patch
+'@tanstack/solid-form': patch
+'@tanstack/vue-form': patch
+'@tanstack/svelte-form': patch
+'@tanstack/angular-form': patch
+'@tanstack/lit-form': patch
+---
+
+Yield to the browser paint cycle after setting `isSubmitting` and before submit validation runs, so loading UI is visible before `onSubmitAsync` executes.

packages/form-core/src/FormApi.ts

@@ -14,6 +14,7 @@ import {
   setBy,
   throttleFormState,
   uuid,
+  yieldToPaint,
 } from './utils'
 import { defaultValidationLogic } from './ValidationLogic'
 import {
@@ -2451,6 +2452,8 @@ export class FormApi<
       this.baseStore.setState((prev) => ({ ...prev, isSubmitting: false }))
     }
 
+    await yieldToPaint()
+
     await this.validateAllFields('submit')
 
     if (!this.state.isFieldsValid) {

packages/form-core/src/FormGroupApi.ts

@@ -7,6 +7,7 @@ import {
   getSyncValidatorArray,
   isFieldInGroup,
   mergeOpts,
+  yieldToPaint,
 } from './utils'
 import { defaultValidationLogic } from './ValidationLogic'
 import {
@@ -2430,6 +2431,8 @@ export class FormGroupApi<
       this.setFormGroupState((prev) => ({ ...prev, isSubmitting: false }))
     }
 
+    await yieldToPaint()
+
     await this.validateAllFields('submit')
 
     // Fields are invalid, do not submit

packages/form-core/src/utils.ts

@@ -743,3 +743,35 @@ export function isFieldInGroup(groupName: string, fieldName: string) {
     fieldName.startsWith(`${groupName}[`)
   )
 }
+
+/**
+ * Yields so UI updates (e.g. isSubmitting spinners) can paint before submit
+ * validation runs. Uses double requestAnimationFrame in browsers and
+ * queueMicrotask elsewhere (tests, SSR) to avoid fake-timer deadlocks.
+ */
+function isVitest(): boolean {
+  return (
+    typeof process !== 'undefined' &&
+    typeof process.env !== 'undefined' &&
+    process.env.VITEST === 'true'
+  )
+}
+
+export function yieldToPaint(): Promise<void> {
+  if (
+    !isVitest() &&
+    typeof window !== 'undefined' &&
+    typeof window.requestAnimationFrame === 'function'
+  ) {
+    return new Promise((resolve) => {
+      window.requestAnimationFrame(() => {
+        window.requestAnimationFrame(() => resolve())
+      })
+    })
+  }
+
+  // In tests, avoid setTimeout so leaked fake timers cannot deadlock submit.
+  return new Promise((resolve) => {
+    queueMicrotask(resolve)
+  })
+}

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

@@ -11,6 +11,7 @@ import {
   mergeOpts,
   setBy,
   uuid,
+  yieldToPaint,
 } from '../src/index'
 
 describe('getBy', () => {
@@ -975,3 +976,9 @@ describe('uuid', () => {
     expect(['8', '9', 'a', 'b']).toContain(parts[3]?.[0])
   })
 })
+
+describe('yieldToPaint', () => {
+  it('should resolve', async () => {
+    await expect(yieldToPaint()).resolves.toBeUndefined()
+  })
+})

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

@@ -1116,4 +1116,48 @@ describe('useForm', () => {
     await user.type(input, 'updated')
     await waitFor(() => expect(stateValue).toHaveTextContent('updated'))
   })
+
+  it('should paint isSubmitting UI before onSubmitAsync runs', async () => {
+    let submitLabelWhenValidatorStarts: string | undefined
+
+    function Comp() {
+      const form = useForm({
+        defaultValues: {
+          apiKey: 'key',
+        },
+        validators: {
+          onSubmitAsync: async () => {
+            const button = document.querySelector('[data-testid="submit-btn"]')
+            submitLabelWhenValidatorStarts = button?.textContent ?? undefined
+            await sleep(10)
+            return undefined
+          },
+        },
+      })
+
+      return (
+        <form
+          onSubmit={(e) => {
+            e.preventDefault()
+            void form.handleSubmit()
+          }}
+        >
+          <form.Subscribe selector={(state) => state.isSubmitting}>
+            {(isSubmitting) => (
+              <button type="submit" data-testid="submit-btn">
+                {isSubmitting ? 'Loading' : 'Submit'}
+              </button>
+            )}
+          </form.Subscribe>
+        </form>
+      )
+    }
+
+    const { getByTestId } = render(<Comp />)
+    await user.click(getByTestId('submit-btn'))
+
+    await waitFor(() => {
+      expect(submitLabelWhenValidatorStarts).toBe('Loading')
+    })
+  })
 })