Org Skills

Signal Forms (`@angular/forms/signals`) — recipe

Supporting material for angular-development. Agents load it on demand; it ships inside the skill folder.

RawSource

Stable since Angular v22.0 (experimental on v21; not available on v20). Verified 2026-09 against https://angular.dev/guide/forms/signals/overview, https://angular.dev/guide/forms/signals/validation, https://angular.dev/api/forms/signals/form, https://angular.dev/api/forms/signals/submit, https://angular.dev/api/forms/signals/FormField, https://angular.dev/guide/forms/signals/comparison.

When to use which forms API

Situation Use Why
New form in a v22+ app Signal Forms Type-safe from the model, validation in one schema, no getRawValue() copies; Angular's own guidance says "prioritise Signal Forms in v22+"
Existing Reactive Forms codebase, or v20/21 Typed Reactive Forms (nonNullable) Stable, not deprecated; do not mix both APIs in one form
Trivial login/search/contact form in a legacy template-driven app Template-driven Only for consistency with what exists

Model, form, field state

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { form, FormField, required, email, minLength, validate, submit } from '@angular/forms/signals';

@Component({
  selector: 'app-profile-form',
  imports: [FormField],
  changeDetection: ChangeDetectionStrategy.OnPush,
  templateUrl: './profile-form.html',
})
export class ProfileForm {
  // The model signal IS the form data — the form does not keep its own copy.
  readonly model = signal({ email: '', displayName: '', website: '' });

  readonly f = form(this.model, (p) => {
    required(p.email, { message: 'Email is required' });
    email(p.email, { message: 'Enter a valid email address' });
    required(p.displayName);
    minLength(p.displayName, 2, { message: 'At least 2 characters' });
    validate(p.website, ({ value }) =>
      value() && !value().startsWith('https://') ? { kind: 'https', message: 'URL must start with https://' } : null);
  });

  protected async save() {
    await submit(this.f, {
      action: async () => {
        const result = await this.api.saveProfile(this.model());   // your service
        return result.ok ? undefined
          : [{ fieldTree: this.f.email, kind: 'server', message: result.message }];   // lands on that field's errors()
      },
    });
  }
}
<form (submit)="$event.preventDefault(); save()">
  <label for="email">Email</label>
  <input id="email" type="email" [formField]="f.email" [attr.aria-invalid]="f.email().invalid()" aria-describedby="email-errors" />
  @if (f.email().touched() && f.email().invalid()) {
    <ul id="email-errors" role="alert">
      @for (e of f.email().errors(); track e.kind) { <li>{{ e.message }}</li> }
    </ul>
  }
  <button type="submit" [disabled]="f().invalid()">Save</button>
</form>

Field state signals: value(), valid(), invalid(), errors(), touched(), pending() (async validation running). Form-level: f().valid(), f().value(). Set programmatically with f.email().value.set('x') or by updating the model signal — both are the same data.

Validators

Need Schema call
Required / email / length required(p.x, { message }), email(p.x), minLength(p.x, n), maxLength(p.x, n), pattern(p.x, /re/)
Custom synchronous rule validate(p.x, ({ value }) => cond ? { kind: 'name', message } : null)
Server check validateHttp(p.username, { request: ({ value }) => /api/check?u=${value()}, onSuccess: (res) => res.taken ? { kind: 'taken', message: '…' } : null })
Array items applyEach(p.items, itemSchema) — array entries keep identity when reordered
Cross-field validate(p.confirm, ({ value, valueOf }) => …) reading sibling values via the field tree

Errors carry { kind, message }; show message in the template, branch on kind for custom UI.

Submission

submit(form, { action }) returns Promise<boolean>, prevents concurrent submissions (a second call returns false), marks fields touched, and routes returned [{ fieldTree, kind, message }] entries to the named fields. Return undefined on success.

Reactive Forms → Signal Forms mapping

Reactive Forms Signal Forms
new FormGroup({ email: new FormControl('', { nonNullable: true, validators: [Validators.required] }) }) signal({ email: '' }) + form(model, p => required(p.email))
formControlName="email" / [formControl] [formField]="f.email"
control.errors?.['required'] f.email().errors() → { kind: 'required', message }
form.valid, form.getRawValue() f().valid(), model()
FormArray + push() array in the model + model.update(m => ({ ...m, items: [...m.items, x] })); validate with applyEach
Async validator validateHttp(...)
form.markAllAsTouched() on submit done by submit()
valueChanges.pipe(debounceTime) computed() / effect() on model(); RxJS via toObservable(model) if debouncing is genuinely needed

Migrate one form at a time: replace the control tree with a model signal, move validators into the schema, swap formControlName for [formField], delete ReactiveFormsModule from imports when the last control is gone.

Custom controls

A custom input binds to a field by implementing the FormValueControl/FormCheckboxControl interfaces from @angular/forms/signals (a value model() plus optional disabled, touched, errors inputs) — see https://angular.dev/guide/forms/signals/custom-controls. Material and Aria controls work with [formField] directly.