Skip to content
< samuelsantana.dev />
Back to the BlogThree phones, only the third touched; after removing the second, FormArray and an object list carry the state with 333, while string[] leaves it at the position.

Migrating Angular Reactive Forms to Signal Forms, One Piece at a Time

Samuel Santana
Published on October 20, 2026
AngularTypeScriptTesting

At the last step of the migration to Signal Forms, all 12 tests for the signup form passed. And that version had a bug: with three phones in the list, removing the second one made the third one's error message disappear.

The list test typed into all three phones before removing one. With all three marked as touched, it made no difference who owned the "touched" state. In Reactive Forms, it belongs to the FormControl, which moves along with the value. In Signal Forms, in a list of strings, it stays stuck to the position.

That was the sneakiest finding of a migration I did on purpose, on a form built with the parts that usually stall a migration, in four steps, with the same test suite running at every step. Everything below came out of that project, on Angular 22.2.3.

The Form and What the CLI Generated

The project started from npx -y @angular/cli@22.2.3 new with --defaults, the latest CLI on October 20, 2026. What comes out of the box says a lot about Angular 22: no zone.js in package.json (zoneless is the default), tests with Vitest 5 and jsdom through the @angular/build:unit-test builder, and TypeScript ~6.0.2, even though TypeScript 7.0.2 has been on npm since July. The ChangeDetectionStrategy declaration in @angular/core 22.2.3 says "OnPush is enabled by default". Reactive Forms worked in that mode with no changes, including the async validator's message, which only arrives after the HTTP response. I removed the welcome page and the router that --defaults creates, so the bundle measures mostly the form.

The form is a signup form with these parts:

  • a nested group (address: street, city, postal code);
  • a dynamic list of phones, in a FormArray;
  • a custom phone control, a ControlValueAccessor that shows (11) 98765-4321 and stores digits only;
  • cross-field validation (password confirmation);
  • an async validator that asks an endpoint whether the email is free, with debounce;
  • a company name field, enabled only for business accounts;
  • a submit that gets a 422 with per-field errors ("address.postalCode") and puts them back on the fields;
  • a draft saved with debounce on every change, without the passwords, and restored on load.

The suite only touches the DOM and the HTTP layer: it types into inputs, fires blur, clicks buttons, reads the message text and answers requests through HttpTestingController. No test reads form.controls or form.valid. That is what lets the same suite run before, during and after the migration (with two adjustments, covered below). A test that looks inside the FormGroup dies at the first step.

Step 1: The Custom Control Switches Contracts

The phone control was a classic ControlValueAccessor: an NG_VALUE_ACCESSOR provider with forwardRef, writeValue, registerOnChange, registerOnTouched, setDisabledState and two callbacks kept in private fields. In Signal Forms, the contract is FormValueControl, and its only required member is a model() named value (below, the component without the formatPhone function):

import { Component, computed, input, model, output } from '@angular/core';
import { FormValueControl } from '@angular/forms/signals';

@Component({
  selector: 'app-phone-input',
  template: `
    <input
      type="tel"
      [attr.aria-label]="label()"
      [value]="display()"
      [disabled]="disabled()"
      (input)="onInput($event)"
      (blur)="touch.emit()"
    />
  `,
})
export class PhoneInput implements FormValueControl<string> {
  /** The only required member of the contract: the form keeps it in sync. */
  readonly value = model('');
  readonly disabled = input(false);
  readonly touch = output<void>();

  readonly label = input('Phone');
  protected readonly display = computed(() => formatPhone(this.value()));

  protected onInput(event: Event): void {
    const el = event.target as HTMLInputElement;
    const digits = el.value.replace(/\D/g, '').slice(0, 11);
    el.value = formatPhone(digits);
    this.value.set(digits);
  }
}

The form didn't change a single line. The template kept <app-phone-input [formControlName]="i" /> inside formArrayName, and the component no longer has any ControlValueAccessor. What connects the two is Reactive Forms' own NgControl: in the 22.2.3 .d.ts it has a "custom control" mode that binds value, disabled, touched and errors straight to the component's inputs. The migration guide says a control like this works in reactive and template-driven forms as-is, and asks you not to implement both interfaces on the same component.

To check it, I wrote a test for the control inside a plain FormGroup, bound with formControlName: the value formatted on the way in, digits in the FormControl while typing, touched on blur, and setValue(), disable() and enable() called from code showing up in the input. The four tests passed with the ControlValueAccessor and passed, unchanged, with the FormValueControl. The component file went from 50 to 36 lines.

This step is independent of the rest. You can do it on a control used by many reactive forms without migrating any of them.

Step 2: One Section Becomes Signal Forms Inside the FormGroup

The compatibility layer exists and lives in @angular/forms/signals/compat. It goes both ways. SignalFormControl is an AbstractControl with Signal Forms rules inside, which you put into an existing FormGroup. compatForm is the opposite: a Signal Forms form whose model can hold reactive FormControls. Both are marked @publicApi 22.0 in the package types.

I migrated the address with SignalFormControl, keeping the root FormGroup (excerpt, other fields omitted):

// Migrated section: Signal Forms rules, still one control inside the reactive FormGroup.
// Declared on its own because FormBuilder types it as AbstractControl and drops fieldTree.
private readonly addressControl = new SignalFormControl<Address>({ street: '', city: '', postalCode: '' }, (address) => {
  required(address.street);
  required(address.city);
  required(address.postalCode);
  pattern(address.postalCode, POSTAL_CODE, { message: messageFor('postalCode') });
  // SignalFormControl.setErrors() throws: a server error has to become a rule.
  validate(address.postalCode, ({ value }) => {
    const error = this.addressServerErrors().postalCode;
    return error && error.value === value() ? { kind: 'server', message: error.message } : null;
  });
});

protected readonly form = this.fb.group(
  {
    // ...the other fields, unchanged
    address: this.addressControl,
    phones: this.fb.array([this.phoneControl()]),
  },
  { validators: passwordsMatch },
);

/** The section's FieldTree, for [formField] in the template. */
protected readonly address = this.addressControl.fieldTree;

In the template, the three inputs swapped formControlName for [formField]="address.street". The rest of the form stayed reactive, and the 16 tests passed. Four differences showed up along the way.

The first is about types. With the SignalFormControl declared directly inside fb.group({...}), the build failed:

TS2339: Property 'fieldTree' does not exist on type 'AbstractControl<any, any, any>'.

The FormBuilder type knows FormControl, FormGroup, FormRecord and FormArray; any other subclass falls into the generic AbstractControl case. Declaring the control in its own class field fixes it.

The second is that, from the reactive side, the section became a leaf. form.get('address') exists; form.get('address.postalCode') returns null. The code that took the 422 and called this.form.get(field)?.setErrors(...) for each error can no longer find the postal code, and needed a detour for that section.

The third explains the code above. The imperative AbstractControl API doesn't work on this class. I called three methods in a separate test, and all three threw:

SignalFormControl.setErrors(): NG01920: Imperatively setting errors is not supported in signal forms. Errors are derived from validation rules.
SignalFormControl.disable(): NG01920: Imperatively changing enabled/disabled status in form control is not supported in signal forms. Instead use a "disabled" rule to derive the disabled status from a signal.
SignalFormControl.setValidators(): NG01920: Dynamically adding and removing validators is not supported in signal forms. Instead use the "applyWhen" rule to conditionally apply validators based on a signal.

So the server error became a rule: a signal keeps the message together with the value the server rejected, and the validate reports the error only while the field still holds that value. When the user edits the postal code, the error goes away, which matches what setErrors does in Reactive Forms (validators run again on change and overwrite the manual error).

The fourth is good news: markAllAsTouched() and patchValue() called on the root FormGroup reached the fields inside the SignalFormControl. The empty submit showed "Required" on street, city and postal code, and the restored draft filled in the address.

The Other Direction: compatForm

I didn't use compatForm in the form, only in isolated tests, to see how it behaves with a reactive FormControl inside the model (simplified code):

const email = new FormControl('ada@', { nonNullable: true, validators: Validators.email });
const model = signal({ name: 'Ada', email });
const f = TestBed.runInInjectionContext(() => compatForm(model, (p) => required(p.name)));

expect(f.email().value()).toBe('ada@');
expect(f().value().email).toBe(email); // the whole value still holds the FormControl itself
expect(extractValue(f)).toEqual({ name: 'Ada', email: 'ada@' });

const [error] = f.email().errors(); // a CompatValidationError
expect(error.kind).toBe('email');

Errors from the reactive validator show up as CompatValidationError, with kind equal to the Reactive Forms key (email, and emailTaken in the async validator test). The value of the whole form carries the FormControl object, and extractValue returns the raw values.

How I'd choose between them: SignalFormControl when the root FormGroup is used by other code (a parent component that receives the group, a service that calls patchValue) and one section can change without anyone outside noticing. compatForm when the form itself can change, but one piece has RxJS logic that isn't worth porting yet, like a complicated async validator.

Step 3: The Whole Form

The last step replaces the FormGroup with a signal holding the model and a schema function with the rules:

protected readonly model = signal<SignupModel>(this.initialModel());

protected readonly form = form(
  this.model,
  (p) => {
    required(p.name);
    required(p.email);
    email(p.email);
    validateHttp(p.email, {
      request: ({ value }) => ({ url: '/api/check-email', params: { email: value() } }),
      debounce: this.timing.emailCheckDebounceMs,
      onSuccess: (result: { available: boolean }) => (result.available ? null : { kind: 'emailTaken' }),
      onError: () => null, // a failed check must not block the user
    });
    required(p.password);
    minLength(p.password, 8);
    required(p.confirmPassword);
    validate(p.confirmPassword, ({ value, valueOf }) =>
      value() && valueOf(p.password) && value() !== valueOf(p.password) ? { kind: 'passwordMismatch' } : null,
    );
    disabled(p.companyName, { when: ({ valueOf }) => valueOf(p.accountType) !== 'business' });
    required(p.companyName);
    required(p.address.street);
    required(p.address.city);
    required(p.address.postalCode);
    pattern(p.address.postalCode, POSTAL_CODE, { message: messageFor('postalCode') });
    applyEach(p.phones, (phone) => {
      required(phone.number);
      pattern(phone.number, PHONE, { message: messageFor('phone') });
    });
  },
  {
    submission: {
      action: (f) => this.send(f),
      // The default, 'pending', submits while the email check is still running.
      ignoreValidators: 'none',
    },
  },
);

In the template, <form [formGroup]="form" (ngSubmit)="submit()" novalidate> became <form [formRoot]="form"> (the FormRoot directive adds novalidate on its own), each formControlName="x" became [formField]="form.x", and the button now reads form().submitting().

Several pieces of the reactive code went away, each one by changing mechanism:

  • The subscription to accountType.valueChanges that called enable() and disable() on the company name became the disabled(..., { when }) rule. A note: passing the function directly, disabled(path, fn), still compiles, but it's marked @deprecated in 22.2; the current form is the object with when.
  • The passwordsMatch group validator became a validate on the confirmation field itself. In Reactive Forms, the error lived on the group, and the template needed a method that merged the group's error with the field's own errors. Now it's just another error on the field.
  • The async validator with timer + switchMap (the debounce had to live inside the validator, because Reactive Forms unsubscribes the previous Observable on every keystroke) became validateHttp with the debounce option. The test that types two emails in a row and expects a single request, for the last one, passed in both versions.
  • Restoring the draft, which had to empty the FormArray and create one FormControl per phone before patchValue (patchValue doesn't grow a FormArray), became the signal's initial value.
  • The loop that called setErrors for each 422 error became the action's return value: a list of { kind, message, fieldTree }. Signal Forms attaches each error to the right field and clears it when the user edits that field, as the form submission guide says.

The submit ended up like this:

private async send(f: FieldTree<SignupModel>) {
  const { confirmPassword, companyName, phones, ...rest } = f().value();
  // The model keeps companyName while it is disabled: leaving it out is now explicit.
  const request = {
    ...rest,
    ...(rest.accountType === 'business' && { companyName }),
    phones: phones.map((p) => p.number),
  };
  try {
    await firstValueFrom(this.http.post('/api/signup', request));
    this.created.set(true);
    this.drafts.clear();
    return null;
  } catch (err) {
    if (!(err instanceof HttpErrorResponse) || err.status !== 422) throw err;
    // No form.get('address.postalCode'): walk the FieldTree by key.
    return (err.error.errors as ServerFieldError[]).map(({ field, message }) => ({
      kind: 'server',
      message,
      fieldTree: field.split('.').reduce((node: any, key) => node[key], f) as FieldTree<unknown>,
    }));
  }
}

The first run of the suite against this version had 5 failures out of 12. Four came from how the tests waited for the screen. One was behavior.

What Didn't Map One to One

Submitting While the Email Check Is Still Running

The test types a new email, clicks submit before the availability check answers, and expects no POST to go out. In Reactive Forms, submit() had if (this.form.invalid || this.form.pending) return;. In Signal Forms, the POST went out:

Error: Expected zero matching requests for criteria "Match method: POST, URL: /api/signup", found 1.

That's the documented default. FormSubmitOptions.ignoreValidators accepts 'pending', 'none' or 'all', and the default is 'pending': pending validators don't block submission. The async operations guide warns that submit() doesn't wait for async validation. With ignoreValidators: 'none', the test passed. In a form where the server validates everything again anyway, the default may be fine. In mine, sending the signup before knowing whether the email exists was exactly what the reactive code avoided.

A List of Strings, and State That Stays at the Position

In the first version of step 3, phones was string[], like the FormArray. The 12 tests passed after the fix above, and the bug from the opening was there. I wrote an isolated test with three items, only the third one touched, removing the second:

it('Signal Forms, array of strings', () => {
  const model = signal({ phones: ['111', '222', '333'] });
  const f = TestBed.runInInjectionContext(() => form(model));
  f.phones[2]().markAsTouched();
  model.update((m) => ({ phones: m.phones.filter((_, i) => i !== 1) }));
  const state = [...f.phones].map((p) => [p().value(), p().touched()]);
  console.log('strings:', JSON.stringify(state));
});

With the same test for a list of objects ({ number: '111' }) and for a FormArray:

strings: [["111",false],["333",false]]
objects: [["111",false],["333",true]]

With the FormArray, the result was ['333', true], because the whole FormControl moves. In a list of strings in Signal Forms, "333" moved to position 1 and inherited position 1's state, which had never been touched. In a list of objects, the state followed the item. The models guide says array items that are objects get a tracking identity automatically; it says nothing about primitives.

On screen, the effect is the error message vanishing from an invalid phone after the user removes another one. The fix was changing the model to phones: { number: string }[], binding [formField]="phone.number", using track phone in the @for and converting back to string[] in the payload and the draft. And the suite got the test it was missing: only the third phone touched, remove the second, the message must be at position 1. It failed with string[] and passed with objects.

whenStable() That Never Comes Back

Of the four remaining failures, two were 5-second timeouts and two were assertions made too early. The suite waited for the screen with await fixture.whenStable(). With validateHttp, the email check is an httpResource, and ResourceImpl in @angular/core 22.2.3 registers a task in PendingTasks while it loads. To Angular, the app isn't stable while the request is in flight; and in the test it only comes back when the test itself calls flush(), which came after the await. The test was waiting for a response it hadn't sent yet.

The other two go through the submit action, which is async: created.set(true) and the 422 errors only happen after the POST promise resolves. My reading, which I didn't instrument, is that whenStable() returned before that. I swapped the helper:

// Not fixture.whenStable(): an in-flight httpResource (validateHttp) is a pending task,
// so whenStable() would wait for a response this test has not flushed yet.
// One macrotask lets promise chains (the async submit action) finish, then render.
const stable = async () => {
  await sleep(0);
  TestBed.tick();
};

That was one of the two changes to the test file during the migration. The other was the new list test. I ran the final suite, with both, against the code of steps 0, 1 and 2: 17 out of 17 on each.

The Smaller Differences

In Reactive FormsIn Signal Forms 22.2What I did
form.value leaves disabled controls outvalue() keeps companyName: '' while the field is disabled; with the naive payload, the POST test failed showing that extra fieldbuild the payload explicitly
form.get('address.postalCode')doesn't existfield.split('.').reduce(...) over the FieldTree
valueChangesdoesn't exist; toObservable(model) emits the current value firstskip(1); without it, an empty draft was saved when the screen opened
minlength errorminLength errormessageFor accepts both
ng-pristine, ng-invalid, ng-touched classes on the inputnone (in Chromium, #name had no class attribute)provideSignalFormsConfig({ classes: NG_STATUS_CLASSES }) brings all three back, for 0.35 kB more in the raw chunk

The draft used to be a subscription to valueChanges with debounceTime, and valueChanges is one of the never-completing sources I listed in the measured RxJS post. It became:

// Signal Forms has no valueChanges. toObservable emits the current value first: skip it.
toObservable(this.model)
  .pipe(skip(1), map(toDraft), debounceTime(this.timing.draftDebounceMs), takeUntilDestroyed())
  .subscribe((draft) => this.drafts.save(draft));

@angular/core 22 has a debounced() function that would do this without RxJS, but it's marked @experimental 22.0. For debouncing a side effect, I kept RxJS.

What It Cost in the Bundle

Each step produced a production build (ng build). I measured the initial chunk raw, with gzip level 9 and with brotli quality 11, using a script that reads the file from dist/. The "Estimated transfer size" the CLI prints matched the brotli figure in all four builds, down to the last decimal it shows; that ng build column is brotli.

StepInitial chunkgzip -9brotli 11Lines of codeManual subscriptions
0. Reactive Forms213.4 kB65.4 kB58.3 kB3203
1. control as FormValueControl214.6 kB65.8 kB58.6 kB3063
2. address as SignalFormControl267.8 kB81.0 kB71.4 kB3263
3. all Signal Forms247.3 kB77.8 kB68.3 kB3181

Lines are the non-blank, non-comment lines of the form's five files (component, template, phone control, validators, model). Subscriptions are the .subscribe( calls in the component: at step 0, accountType.valueChanges, form.valueChanges and the POST; at step 3, only the draft.

The final version is 10.0 kB larger in brotli than the original. The esbuild metafile (ng build --stats-json) shows where it comes from. At step 0, the @angular/forms package took 43.0 kB minified. At step 3, it takes 62.0 kB: 14.5 kB from the signals entry, 26.7 kB from a shared validation chunk, and still 20.8 kB from the main entry, which signals imports (NgControl, Validators, NG_VALUE_ACCESSOR, for interop). On top of that, validateHttp uses httpResource, and the resource code from @angular/core and @angular/common/http went from 0.2 kB to 12.0 kB. The form's own code shrank from 10.5 to 9.9 kB.

Step 2 is the most expensive: both systems loaded together, 13.1 kB of brotli above the original. These numbers come from an app that has only this form. As long as any other form in the app stays reactive, Reactive Forms stays in the bundle, and the cost of each migrated screen should land closer to step 2 than to step 3. I didn't measure that.

And the code didn't shrink. It was 320 lines before and 318 after. What changed was where it lives: validators.ts went from 19 to 2 lines, the component from 106 to 135, and 20 of those lines are the model interface and the initial object, which FormBuilder used to infer.

The four builds also ran in a real Chromium 156, through Playwright, with an interceptor that fakes the API with 300 to 400 ms of latency: email already registered, phone formatted while typing, server errors on email and postal code, the postal code error going away on edit, account created, and the draft surviving a reload with two phones. All six checks passed on all four builds, with no console errors.

When Not to Migrate

The Signal Forms overview itself says that in an existing app with reactive forms, they "remain a solid choice". The API is stable: the entry's public symbols are marked @publicApi 22.0 (except for an experimental WebMCP helper), and the 22.0.0 changelog (June 3, 2026) has the entry "graduate signal forms APIs to public API". Stable doesn't mean the migration pays for itself. In my opinion, after this exercise, it isn't worth it in these cases:

When the form depends on the imperative API from outside of it. An interceptor that calls setErrors on any control, a service that calls addValidators based on remote config, a parent component that calls disable() on a group. While both systems coexist, SignalFormControl throws NG01920 on setErrors, disable and setValidators (the three I tested; the migration guide also lists addValidators and removeValidators), and in the end each use has to become a rule declared in the schema. If that logic is spread across the app, the migration is about that logic, not about the form.

When the bundle is what matters and the form is the only forms usage on the page. Here it was 10.0 kB of brotli more at the end, and 13.1 kB while both coexisted.

When the form works and isn't going to change. The migration swaps mechanisms without reducing code, and it brings behavior differences that only show up with tests: submitting with pending validation and list state staying at the position went unnoticed until the suite, or a new test, pointed them out.

When the form's tests read form.controls and form.valid. Then the migration rewrites the tests along with the code, and they stop being a safety net. In my case, both behavior differences surfaced because the tests went through the DOM and stayed valid across all four steps.

Third-party components that only offer a ControlValueAccessor aren't, on their own, a reason to wait: the FormField directive's documentation says it accepts a component with a ControlValueAccessor, a path that "should only be used for backwards compatibility". I didn't test that path.

What I'd do in any Angular 22 project is step 1. It's cheap (50 to 36 lines, 0.3 kB of brotli), it doesn't require touching any form and, according to the docs, it leaves the control ready for Signal Forms, Reactive Forms and template-driven forms. New forms I start in Signal Forms. Existing ones get migrated one at a time, when they were going to be touched anyway, after their suite has a test that removes an item from the middle of a list.

I didn't measure forms with hundreds of fields, typing latency, Firefox, Safari or server-side rendering.

Comments

Loading comments...