Template-Driven Forms
What template-driven forms are
Section titled “What template-driven forms are”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:
nameis mandatory on everyngModel. The directive registers with the parentNgFormby name; without one, Angular throws, or the control is silently absent fromf.value.#f="ngForm"exports the directive instance.#falone gives you the DOM<form>element, which has none of the state you want.- Use
(ngSubmit), not(submit).ngSubmitfires after Angular has updated its controls and does not navigate the page.
Reading control state
Section titled “Reading control state”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.
One-way binding
Section titled “One-way binding”[(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 }".
Deferring updates
Section titled “Deferring updates”<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.
Custom validation
Section titled “Custom validation”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.
Programmatic control
Section titled “Programmatic control”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.
When to stop using template-driven forms
Section titled “When to stop using template-driven forms”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.
Testing
Section titled “Testing”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.
Common mistakes
Section titled “Common mistakes”| 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 |
Migrating away
Section titled “Migrating away”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.
Related pages
Section titled “Related pages”- Angular Forms: Reactive, Template-Driven and Signal Forms
- Signals and Angular Reactivity
- Angular Testing: From First Test to Large Suites
- Forms basics