fix(forms): warn when showing hidden field state

mmalerba · web-flow · commit d75046bc0916 · 2026-02-11T14:46:43.000-08:00
In signal forms, it is up to the user to guard hidden fields from being
rendered in the template. To help catch instances where it is
accidentally not guarded, this commit introduces a warning in dev mode.
diff --git a/packages/forms/signals/src/directive/form_field_directive.ts b/packages/forms/signals/src/directive/form_field_directive.ts
@@ -14,6 +14,7 @@ import {
   Directive,
   effect,
   ElementRef,
+  ɵformatRuntimeError as formatRuntimeError,
   inject,
   InjectionToken,
   Injector,
@@ -240,7 +241,9 @@ export class FormField<T> {
     if (this.isFieldBinding) {
       throw new RuntimeError(
         RuntimeErrorCode.BINDING_ALREADY_REGISTERED,
-        ngDevMode && 'FormField already registered as a binding',
+        typeof ngDevMode !== 'undefined' &&
+          ngDevMode &&
+          'FormField already registered as a binding',
       );
     }
     this.isFieldBinding = true;
@@ -269,6 +272,25 @@ export class FormField<T> {
       },
       {injector: this.injector},
     );
+
+    if (typeof ngDevMode !== 'undefined' && ngDevMode) {
+      effect(
+        () => {
+          const fieldNode = this.state() as unknown as FieldNode;
+          if (fieldNode.hidden()) {
+            const path = fieldNode.structure.pathKeys().join('.') || '<root>';
+            console.warn(
+              formatRuntimeError(
+                RuntimeErrorCode.RENDERED_HIDDEN_FIELD,
+                `Field '${path}' is hidden but is being rendered. ` +
+                  `Hidden fields should be removed from the DOM using @if.`,
+              ),
+            );
+          }
+        },
+        {injector: this.injector},
+      );
+    }
   }
 
   /**
@@ -301,7 +323,8 @@ export class FormField<T> {
     } else {
       throw new RuntimeError(
         RuntimeErrorCode.INVALID_FIELD_DIRECTIVE_HOST,
-        ngDevMode &&
+        typeof ngDevMode !== 'undefined' &&
+          ngDevMode &&
           `${host.descriptor} is an invalid [formField] directive host. The host must be a native form control ` +
             `(such as <input>', '<select>', or '<textarea>') or a custom form control with a 'value' or ` +
             `'checked' model.`,
diff --git a/packages/forms/signals/src/errors.ts b/packages/forms/signals/src/errors.ts
@@ -28,5 +28,6 @@ export const enum RuntimeErrorCode {
   BINDING_ALREADY_REGISTERED = 1913,
   INVALID_FIELD_DIRECTIVE_HOST = 1914,
   MISSING_SUBMIT_ACTION = 1915,
+  RENDERED_HIDDEN_FIELD = 1916,
   UNSUPPORTED_FEATURE = 1920,
 }
diff --git a/packages/forms/signals/test/web/form_field_directive.spec.ts b/packages/forms/signals/test/web/form_field_directive.spec.ts
@@ -779,6 +779,51 @@ describe('field directive', () => {
         act(() => component.field.set(component.f.y));
         expect(component.customControl().hidden()).toBe(false);
       });
+
+      it('should warn when a hidden field is rendered', () => {
+        const warnSpy = spyOn(console, 'warn');
+        @Component({
+          imports: [FormField],
+          template: `<input [formField]="f" />`,
+        })
+        class TestCmp {
+          readonly f = form(signal(''), (p) => {
+            hidden(p, () => true);
+          });
+        }
+
+        act(() => TestBed.createComponent(TestCmp));
+        expect(warnSpy).toHaveBeenCalledWith(
+          jasmine.stringMatching(/Field '.*' is hidden but is being rendered/),
+        );
+      });
+
+      it('should not warn when a hidden field is guarded by @if', () => {
+        const isHidden = signal(false);
+        const warnSpy = spyOn(console, 'warn');
+        @Component({
+          imports: [FormField],
+          template: `
+            @if (!f().hidden()) {
+              <input [formField]="f" />
+            }
+          `,
+        })
+        class TestCmp {
+          readonly f = form(signal(''), (p) => {
+            hidden(p, isHidden);
+          });
+        }
+
+        act(() => TestBed.createComponent(TestCmp));
+        expect(warnSpy).not.toHaveBeenCalled();
+
+        act(() => isHidden.set(true));
+        expect(warnSpy).not.toHaveBeenCalled();
+
+        act(() => isHidden.set(false));
+        expect(warnSpy).not.toHaveBeenCalled();
+      });
     });
 
     describe('invalid', () => {

Original file line number	Diff line number	Diff line change
`@@ -28,5 +28,6 @@ export const enum RuntimeErrorCode {`
`28`	`28`	`BINDING_ALREADY_REGISTERED = 1913,`
`29`	`29`	`INVALID_FIELD_DIRECTIVE_HOST = 1914,`
`30`	`30`	`MISSING_SUBMIT_ACTION = 1915,`
	`31`	`+ RENDERED_HIDDEN_FIELD = 1916,`
`31`	`32`	`UNSUPPORTED_FEATURE = 1920,`
`32`	`33`	`}`