feat(core): form identifiers (#1659)

harry-whorlow · web-flow · commit 2c9bab085801 · 2025-08-05T15:41:45.000+02:00
diff --git a/packages/form-core/src/FormApi.ts b/packages/form-core/src/FormApi.ts
@@ -376,6 +376,10 @@ export interface FormOptions<
   in out TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
   in out TSubmitMeta = never,
 > extends BaseFormOptions<TFormData, TSubmitMeta> {
+  /**
+   * The form name, used for devtools and identification
+   */
+  formId?: string
   /**
    * The default state for the form.
    */
@@ -1238,6 +1242,10 @@ export class FormApi<
     this.update(opts || {})
   }
 
+  get formId(): string | undefined {
+    return this.options.formId
+  }
+
   /**
    * @private
    */
diff --git a/packages/form-core/tests/FormApi.spec.ts b/packages/form-core/tests/FormApi.spec.ts
@@ -3944,3 +3944,13 @@ it('should preserve nested fields on resetField if defaultValues is not provided
   form.resetField('nested.field.name')
   expect(form.state.values.nested.field.name).toEqual('Nested')
 })
+
+it('should accept formId and return it', () => {
+  const form = new FormApi({
+    defaultValues: { age: 0 },
+    formId: 'age',
+  })
+  form.mount()
+
+  expect(form.formId).toEqual('age')
+})
diff --git a/packages/react-form/tests/createFormHook.test.tsx b/packages/react-form/tests/createFormHook.test.tsx
@@ -450,4 +450,50 @@ describe('createFormHook', () => {
     const inputField1 = getByLabelText('unrelated')
     expect(inputField1).toHaveValue('John')
   })
+
+  it('should accept formId and return it', async () => {
+    function Submit() {
+      const form = useFormContext()
+
+      return (
+        <button type="submit" form={form.formId} data-testid="formId-target">
+          {form.formId}
+        </button>
+      )
+    }
+
+    function Comp() {
+      const form = useAppForm({
+        formId: 'test',
+      })
+
+      return (
+        <form.AppForm>
+          <form
+            id={form.formId}
+            onSubmit={(e) => {
+              e.preventDefault()
+              form.handleSubmit()
+            }}
+          ></form>
+
+          <form.Subscribe
+            selector={(state) => state.submissionAttempts}
+            children={(submissionAttempts) => (
+              <span data-testid="formId-result">{submissionAttempts}</span>
+            )}
+          />
+
+          <Submit />
+        </form.AppForm>
+      )
+    }
+
+    const { getByTestId } = render(<Comp />)
+    const target = getByTestId('formId-target')
+    const result = getByTestId('formId-result')
+
+    await user.click(target)
+    expect(result).toHaveTextContent('1')
+  })
 })
diff --git a/packages/react-form/tests/useForm.test.tsx b/packages/react-form/tests/useForm.test.tsx
@@ -854,4 +854,42 @@ describe('useForm', () => {
     await user.click(submit)
     await waitFor(() => expect(input).toHaveValue('another-test'))
   })
+
+  it('should accept formId and return it', async () => {
+    function Comp() {
+      const form = useForm({
+        formId: 'test',
+      })
+
+      return (
+        <>
+          <form
+            id={form.formId}
+            onSubmit={(e) => {
+              e.preventDefault()
+              form.handleSubmit()
+            }}
+          ></form>
+
+          <form.Subscribe
+            selector={(state) => state.submissionAttempts}
+            children={(submissionAttempts) => (
+              <span data-testid="formId-result">{submissionAttempts}</span>
+            )}
+          />
+
+          <button type="submit" form={form.formId} data-testid="formId-target">
+            {form.formId}
+          </button>
+        </>
+      )
+    }
+
+    const { getByTestId } = render(<Comp />)
+    const target = getByTestId('formId-target')
+    const result = getByTestId('formId-result')
+
+    await user.click(target)
+    expect(result).toHaveTextContent('1')
+  })
 })
