Forms Architecture

Relevant source files

• adev/src/content/best-practices/runtime-performance/BUILD.bazel
• adev/src/content/best-practices/runtime-performance/skipping-subtrees.md
• adev/src/content/examples/reactive-forms/src/app/app.component.ts
• adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts
• adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts
• adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts
• adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts
• adev/src/content/examples/reactive-forms/src/main.ts
• adev/src/content/guide/components/BUILD.bazel
• adev/src/content/guide/components/anatomy-of-components.md
• adev/src/content/guide/components/lifecycle.md
• adev/src/content/guide/di/BUILD.bazel
• adev/src/content/guide/forms/BUILD.bazel
• adev/src/content/guide/forms/dynamic-forms.md
• adev/src/content/guide/forms/form-validation.md
• adev/src/content/guide/forms/overview.md
• adev/src/content/guide/forms/reactive-forms.md
• adev/src/content/guide/forms/template-driven-forms.md
• adev/src/content/guide/forms/typed-forms.md
• adev/src/content/introduction/essentials/BUILD.bazel
• adev/src/content/introduction/essentials/components.md
• goldens/public-api/forms/index.api.md
• 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

This document describes the architecture of Angular's Forms system, which provides two approaches for handling user input: Template-driven forms and Reactive forms. The Forms system manages form controls, validation, state tracking, and synchronization between the DOM and the application model.

This page covers:

• Core control abstractions (AbstractControl, FormControl, FormGroup, FormArray)
• The ControlValueAccessor bridge pattern
• Forms rendering and data flow models
• Validation architecture and event streams

For detailed guides on specific implementations, see Template-Driven Forms and Reactive Forms and Signal Forms.

---

Core Control Hierarchy

The Forms system is built on a hierarchy of classes that represent form inputs and their organizational structure. All controls derive from AbstractControl.

Control Class Hierarchy

Sources: packages/forms/src/model/abstract_model.ts25-109 packages/forms/src/model/form_group.ts188-194 packages/forms/src/model/form_array.ts122-125

AbstractControl State Machine

AbstractControl tracks the value, validity status, and user interaction state (pristine/touched) of a form element.

Status	Constant	Description
VALID	VALID	No errors exist in the input value packages/forms/src/model/abstract_model.ts44
INVALID	INVALID	An error exists in the input value packages/forms/src/model/abstract_model.ts51
PENDING	PENDING	Async validation is occurring packages/forms/src/model/abstract_model.ts60
DISABLED	DISABLED	Control is exempt from validity/value calculations packages/forms/src/model/abstract_model.ts69

Sources: packages/forms/src/model/abstract_model.ts44-86 goldens/public-api/forms/index.api.md34-43

---

Control Value Accessor (CVA) Bridge

The ControlValueAccessor interface acts as a bridge between Angular's FormControl instances and built-in DOM elements. It abstracts the underlying DOM interaction, allowing the forms API to work with any type of input.

CVA Interface Structure

Classes implementing ControlValueAccessor must provide the following methods:

• writeValue(obj: any): Writes a new value from the form model to the view (DOM) packages/forms/test/reactive_integration_spec.ts127
• registerOnChange(fn: any): Registers a callback function that is called when the value changes in the view packages/forms/test/reactive_integration_spec.ts128
• registerOnTouched(fn: any): Registers a callback function that is called by the forms API on HTTP/DOM blur events packages/forms/test/reactive_integration_spec.ts129

Natural Language to Code Entity Mapping: CVA

Sources: adev/src/content/guide/forms/overview.md66 packages/forms/test/reactive_integration_spec.ts114-132

---

Forms Rendering and Data Flow

Angular supports two data flow models: Synchronous (Reactive) and Asynchronous (Template-driven).

Reactive Data Flow (Model-to-View)

In reactive forms, the component class is the source of truth.

1. The developer calls FormControl.setValue().
2. FormControl notifies the ControlValueAccessor.
3. The ControlValueAccessor updates the DOM element.

Template-Driven Data Flow (View-to-Model)

1. The user types into an <input>.
2. The DOM element emits an input event.
3. The ControlValueAccessor catches the event and calls the registered onChange callback.
4. The NgModel directive updates the internal FormControl instance.
5. The FormControl emits a value through the valueChanges observable.

Sources: adev/src/content/guide/forms/overview.md35 adev/src/content/guide/forms/reactive-forms.md8-10 adev/src/content/guide/forms/overview.md91-95

---

Validation Architecture

Validation is handled by functions that take an AbstractControl and return ValidationErrors or null.

Sync vs Async Validators

• Sync Validators: Functions that return errors immediately. Passed as the second argument to a FormControl adev/src/content/guide/forms/form-validation.md49
• Async Validators: Functions that return a Promise or Observable. Passed as the third argument adev/src/content/guide/forms/form-validation.md50 Angular only runs async validators if all sync validators pass adev/src/content/guide/forms/form-validation.md52

Validator Code Mapping

Sources: adev/src/content/guide/forms/form-validation.md60-67 packages/forms/src/model/abstract_model.ts25

---

Events and Observables

The forms system uses RxJS observables to track state changes across the AbstractControl hierarchy.

Control Events

The events property on AbstractControl emits specific event types packages/forms/src/model/abstract_model.ts89-100:

• ValueChangeEvent: Fired when the value changes packages/forms/src/model/abstract_model.ts109
• StatusChangeEvent: Fired when validation status changes packages/forms/src/model/abstract_model.ts156
• PristineChangeEvent: Fired when the pristine state toggles packages/forms/src/model/abstract_model.ts124
• TouchedChangeEvent: Fired when the touched state changes packages/forms/src/model/abstract_model.ts140

Value and Status Streams

• valueChanges: Emits the latest value goldens/public-api/forms/index.api.md108
• statusChanges: Emits the latest FormControlStatus goldens/public-api/forms/index.api.md96

Sources: packages/forms/src/model/abstract_model.ts89-188 goldens/public-api/forms/index.api.md95-108