Forms System

Relevant source files

• adev/src/content/guide/forms/signals/form-submission.md
• goldens/public-api/forms/index.api.md
• goldens/public-api/forms/signals/compat/index.api.md
• goldens/public-api/forms/signals/index.api.md
• packages/animations/src/version.ts
• packages/core/src/render3/instructions/control.ts
• packages/core/src/render3/interfaces/control.ts
• packages/forms/signals/compat/public_api.ts
• packages/forms/signals/compat/src/api/extract.ts
• packages/forms/signals/compat/src/compat_structure.ts
• packages/forms/signals/src/api/control.ts
• packages/forms/signals/src/api/rules/validation/validate_async.ts
• packages/forms/signals/src/api/structure.ts
• packages/forms/signals/src/api/types.ts
• packages/forms/signals/src/field/context.ts
• packages/forms/signals/src/field/manager.ts
• packages/forms/signals/src/field/node.ts
• packages/forms/signals/src/field/resolution.ts
• packages/forms/signals/src/field/structure.ts
• packages/forms/signals/src/field/submit.ts
• packages/forms/signals/src/field/validation.ts
• packages/forms/signals/src/schema/logic.ts
• packages/forms/signals/src/schema/logic_node.ts
• packages/forms/signals/src/schema/schema.ts
• packages/forms/signals/test/node/compat/extract_value.spec.ts
• packages/forms/signals/test/node/field_context.spec.ts
• packages/forms/signals/test/node/field_node.spec.ts
• packages/forms/signals/test/node/logic_node.spec.ts
• packages/forms/signals/test/node/resource.spec.ts
• packages/forms/signals/test/node/submit.spec.ts
• packages/forms/signals/test/node/types.spec.ts
• packages/forms/signals/test/node/validation_status.spec.ts
• packages/forms/signals/test/web/compat_form.spec.ts
• packages/forms/signals/test/web/dynamic_binding.spec.ts
• packages/forms/signals/test/web/focus.spec.ts
• packages/forms/signals/test/web/orphan_repro.spec.ts
• packages/forms/src/directives/abstract_control_directive.ts
• packages/forms/src/directives/validators.ts
• packages/forms/src/form_builder.ts
• packages/forms/src/model/abstract_model.ts
• packages/forms/src/model/form_array.ts
• packages/forms/src/model/form_control.ts
• packages/forms/src/model/form_group.ts
• packages/forms/src/validators.ts
• packages/forms/test/BUILD.bazel
• packages/forms/test/directives_spec.ts
• packages/forms/test/form_array_spec.ts
• packages/forms/test/form_builder_spec.ts
• packages/forms/test/form_control_spec.ts
• packages/forms/test/form_group_spec.ts
• packages/forms/test/reactive_integration_spec.ts
• packages/forms/test/template_integration_spec.ts
• packages/forms/test/typed_integration_spec.ts
• packages/forms/test/util.ts
• packages/forms/test/validators_spec.ts
• packages/forms/test/value_accessor_integration_spec.ts

Purpose and Scope

The Forms System provides infrastructure for creating and managing forms in Angular applications. It handles user input, validation, state tracking, and synchronization between TypeScript models and HTML form elements. Angular offers three primary approaches:

1. Template-Driven Forms: Declarative, directive-based approach where the form model is implicitly created from the template.
2. Reactive Forms: Imperative, model-driven approach where the form model is explicitly defined in TypeScript.
3. Signal Forms (Experimental): A new reactivity model based on Angular Signals, offering fine-grained updates and improved type safety packages/forms/signals/src/api/structure.ts102-152

This document covers the high-level architecture and how these systems relate. For deep dives, see the child pages.

---

Forms Architecture Overview

The forms system is built on a shared foundation of control abstractions and value accessors that bridge the gap between the framework and the DOM.

Sources: packages/forms/src/model/abstract_model.ts25-109 packages/forms/signals/src/api/structure.ts102-152 packages/core/src/render3/instructions/control.ts38-86

---

Core Abstractions

AbstractControl Hierarchy

In traditional forms, AbstractControl is the base class packages/forms/src/model/abstract_model.ts93-100 It tracks:

• Status: VALID, INVALID, PENDING, or DISABLED packages/forms/src/model/abstract_model.ts44-86
• Interaction: pristine vs dirty and touched vs untouched packages/forms/src/model/abstract_model.ts119-147
• Events: An observable stream of ControlEvent objects including ValueChangeEvent and StatusChangeEvent packages/forms/src/model/abstract_model.ts109-163

For details on the control hierarchy and rendering model, see Forms Architecture.

Signal-Based Field State

The new signal-based forms introduce FieldState, which exposes form data as signals rather than Observables packages/forms/signals/src/api/types.ts138-151

• value: A WritableSignal<T> representing the current data packages/forms/signals/src/field/node.ts163-165
• valid/invalid: Computed signals derived from validation logic packages/forms/signals/src/field/node.ts187-193
• fieldTree: A proxy object that allows navigating the form structure using standard property access (e.g., myForm.address.city()) packages/forms/signals/src/field/node.ts88-91

---

Comparison of Approaches

Feature	Template-Driven	Reactive	Signal Forms
Model Creation	Implicit (Directives)	Explicit (TypeScript)	Explicit (Signals)
Data Flow	Asynchronous	Synchronous	Reactive (Signals)
Validation	Directives	Functions	Schema/Logic Nodes
Type Safety	Low	Improved (v14+)	High (Inferred)

Template-Driven Forms

Best for simple forms where logic is minimal. It relies on directives like NgModel and NgForm. For details, see Template-Driven Forms.

Reactive and Signal Forms

Reactive Forms provide a robust, immutable way to manage form state using FormControl, FormGroup, and FormArray.

Signal Forms (Experimental) represent the future of Angular forms, integrating directly with the Signals reactivity model. They use a form() function to wrap model data packages/forms/signals/src/api/structure.ts102-152 and support advanced features like debounce and disabled logic bound directly to the schema packages/forms/signals/src/api/types.ts97-105

A Compat Layer exists to allow Signal Forms to interoperate with traditional AbstractControl based components goldens/public-api/forms/signals/compat/index.api.md18-58

For details, see Reactive Forms and Signal Forms.

---

System Integration

The forms system integrates with the Angular renderer through special instructions like ɵɵcontrolCreate and ɵɵcontrolUpdate packages/core/src/render3/instructions/control.ts38-68 These instructions manage the lifecycle of form directives and ensure that ControlValueAccessor instances are correctly initialized and updated during change detection cycles packages/core/src/render3/instructions/control.ts42-59

Sources: packages/core/src/render3/instructions/control.ts1-86 packages/forms/src/model/abstract_model.ts1-100

---

Validation and Metadata

Validation in the new signal system is handled via a Schema that defines rules like required, email, or pattern goldens/public-api/forms/signals/index.api.md117-129 It supports:

• Sync Validation: Immediate checks against the current value.
• Async Validation: Integration with Resource for asynchronous checks goldens/public-api/forms/signals/index.api.md47-54
• Metadata: Custom keys can be attached to fields to track UI state or supplementary data goldens/public-api/forms/signals/index.api.md85-94

Sources: packages/forms/signals/src/api/types.ts140-185 packages/forms/signals/src/field/node.ts75-105