Skip to content

Template-Driven Forms

In a template-driven form, the template is the source of truth. The NgModel directive creates and manages a FormControl for each input behind the scenes, and NgForm collects them into a form. You never construct a form model in the component class.

That is the entire appeal: for a contact form or a login box, there is nothing to build. It is also the entire limitation — the form model is implicit, so it cannot be reused, inspected, or manipulated programmatically the way a reactive form’s can.

For choosing between the three form systems, see Angular Forms.

FormsModule must be imported by the standalone component:

@Component({
selector: 'contact-form',
imports: [FormsModule],
templateUrl: './contact-form.html',
})
export class ContactForm {
readonly model = { name: '', email: '', message: '' };
save(form: NgForm): void {
if (form.invalid) return;
this.api.sendMessage(this.model);
}
}
<form #f="ngForm" (ngSubmit)="save(f)">
<label for="name">Name</label>
<input id="name" name="name" [(ngModel)]="model.name" required />
<label for="email">Email</label>
<input id="email" name="email" type="email" [(ngModel)]="model.email" required email />
<button type="submit">Send</button>
</form>

Three requirements produce most first-time errors:

  • name is mandatory on every ngModel. The directive registers with the parent NgForm by name; without one, Angular throws, or the control is silently absent from f.value.
  • #f="ngForm" exports the directive instance. #f alone gives you the DOM <form> element, which has none of the state you want.
  • Use (ngSubmit), not (submit). ngSubmit fires after Angular has updated its controls and does not navigate the page.

Export the directive on the input to reach its state:

<input
id="email"
name="email"
type="email"
[(ngModel)]="model.email"
required
email
#emailCtrl="ngModel"
[attr.aria-invalid]="emailCtrl.invalid && emailCtrl.touched"
[attr.aria-describedby]="emailCtrl.invalid && emailCtrl.touched ? 'email-error' : null"
/>
@if (emailCtrl.invalid && emailCtrl.touched) {
<p id="email-error" class="error">
@if (emailCtrl.errors?.['required']) { Email is required. }
@if (emailCtrl.errors?.['email']) { Enter a valid email address. }
</p>
}

Available on both NgModel and NgForm: valid, invalid, pending, pristine, dirty, touched, untouched, errors, value. Angular also mirrors these onto the element as CSS classes — ng-valid, ng-invalid, ng-touched, ng-dirty, ng-pristine — which is convenient for styling but a poor basis for logic.

Gate error display on touched (or on submission), or the form is covered in red errors before the user has typed anything.

The aria-describedby and aria-invalid bindings above are not optional extras. Without them a screen-reader user hears the field’s label and nothing about why it was rejected.

[(ngModel)] is two-way. When you want NgModel’s validation and state tracking without writing back to a property, use the one-way form:

<input name="q" [ngModel]="query" (ngModelChange)="onQuery($event)" />

And when an input inside a <form> should not be part of the form model at all, add [ngModelOptions]="{ standalone: true }".

<input name="email" [(ngModel)]="model.email" [ngModelOptions]="{ updateOn: 'blur' }" />

updateOn accepts 'change' (default), 'blur' or 'submit'. Use 'blur' for anything that triggers an async validator, or you validate on every keystroke.

This is where template-driven forms cost the most. A custom rule must be a directive, not a function:

@Directive({
selector: '[skuFormat]',
providers: [{ provide: NG_VALIDATORS, useExisting: SkuFormatDirective, multi: true }],
})
export class SkuFormatDirective implements Validator {
validate(control: AbstractControl): ValidationErrors | null {
return /^[A-Z]{3}-\d{4}$/.test(control.value ?? '') ? null : { skuFormat: true };
}
}
<input name="sku" [(ngModel)]="model.sku" skuFormat />

multi: true is essential. NG_VALIDATORS is a multi-provider token; without the flag, your directive replaces every other validator on the element and required silently stops working.

Async validators use NG_ASYNC_VALIDATORS and return Promise<ValidationErrors | null> or Observable<ValidationErrors | null>.

Cross-field validation goes on the <form> element as a validator directive that reads sibling controls from the NgForm — workable, but noticeably more ceremony than the equivalent reactive FormGroup validator or Signal Forms validateTree(). If you are writing cross-field rules, that is a strong signal you have outgrown this system.

NgForm exposes some of the underlying model:

save(form: NgForm): void {
if (form.invalid) {
form.control.markAllAsTouched(); // reveal every error at once
return;
}
this.api.sendMessage(form.value).subscribe(() => form.resetForm());
}

resetForm() clears values and resets touched/pristine; reset() on the underlying control only clears values, leaving the form dirty and touched. Almost always you want resetForm().

form.control is the FormGroup NgForm built, so anything on FormGroup is reachable through it. Reaching for it often, though, means you wanted a reactive form.

Move to reactive or Signal Forms when any of these appear:

  • Dynamic fields. Adding and removing controls at runtime has no clean template-driven expression.
  • Cross-field validation. Awkward here, native there.
  • Reusable form models. The model is implicit, so it cannot be shared or composed.
  • Complex conditional validation. Rules that depend on other rules become a tangle of directives.
  • Tests that need choreography. Covered below — this is the practical tipping point for most teams.

Template-driven forms are the hardest of the three to test, and the reason is structural. The model-to-view data flow is asynchronous: NgModel queues the control update in ngOnChanges and it lands on the next tick, deliberately, to avoid ExpressionChangedAfterItHasBeenChecked.

it('reflects the model in the input', async () => {
const fixture = TestBed.createComponent(ContactForm);
fixture.componentInstance.model.email = 'user@example.test';
await fixture.whenStable(); // waits for the queued control update
const input: HTMLInputElement = fixture.nativeElement.querySelector('input[name="email"]');
expect(input.value).toBe('user@example.test');
});
it('updates the model from the input', async () => {
const fixture = TestBed.createComponent(ContactForm);
await fixture.whenStable();
const input: HTMLInputElement = fixture.nativeElement.querySelector('input[name="email"]');
input.value = 'typed@example.test';
input.dispatchEvent(new Event('input'));
await fixture.whenStable();
expect(fixture.componentInstance.model.email).toBe('typed@example.test');
});

Every test needs a rendered fixture and at least one stabilisation point. A reactive form’s equivalent assertions need neither. See the testing guide.

Mistake Consequence Fix
Missing name Runtime error, or control absent from f.value Add name to every ngModel
#f instead of #f="ngForm" #f is the DOM element, not the directive Export the directive
(submit) instead of (ngSubmit) Page navigates; control state not settled Use (ngSubmit)
Errors shown before touched Form is red on arrival Gate on touched or submission
Custom validator without multi: true Replaces all other validators Add multi: true
reset() instead of resetForm() Values cleared but form stays dirty and touched Use resetForm()
disabled attribute on an ngModel input Angular warns; the state is not tracked Bind [disabled] to a property, or use reactive forms
No <label for> / aria-describedby Errors are invisible to assistive technology Label every input; associate errors
Async validator on updateOn: 'change' A request per keystroke updateOn: 'blur'
Client validation treated as sufficient Bypassable entirely Validate on the server too

To reactive forms, the mapping is mechanical: each ngModel becomes a FormControl with the directive’s validators as functions, and [(ngModel)]="model.x" in the template becomes formControlName="x". Do it one form at a time; the two systems can coexist in an application, just not on the same element.

To Signal Forms, the model becomes a signal() of the same object shape, and the validator directives become entries in one schema function. Note the constraint: the Signal Forms model must be plain objects and arrays — class instances lose their prototype on the first write.