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

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

```ts
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()
      },
    });
  }
}
```

```html
<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.
