Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 74 ยท Templates and Data Binding

Two-Way Binding and model()

Understand Angular two-way binding - the banana-in-a-box syntax, [(ngModel)] with FormsModule, model() signal inputs, and how it all desugars to one input plus one output.

Sometimes data has to flow in both directions. A text box shows the current name, and when the user types, the name in your component must change too. With the two bindings you already know you could do it yourself: [value]="name()" to push the value down and (input)="..." to pull changes up. Two-way binding is a shorthand that writes both halves in one go: [(value)]="name".

This lesson explains the syntax (nicknamed "banana in a box"), shows the common [(ngModel)] form for inputs, introduces model() for your own components, and, most importantly, shows that two-way binding is not a new mechanism: it is one input plus one output with a naming rule. You should be comfortable with property binding and event binding.

Angular's compiler is not available on this site, so Angular code blocks are read-only. The runnable <TryIt> examples are stand-ins that re-create the idea in plain TypeScript and JavaScript.

Banana in a box

The syntax is square brackets (the box) around parentheses (the banana): [( )]. Remember it as "the banana sits inside the box."

HTML
<app-stepper [(value)]="quantity" />

That line means exactly the same as this one:

HTML
<app-stepper [value]="quantity()" (valueChange)="quantity.set($event)" />

The rule is simple: for a two-way binding on a property named x, Angular looks for an input called x and an output called xChange. The parent passes its value down through the input, and whenever the child emits xChange, the parent stores the new value. Because the parent's state is the single source of truth, both sides always agree.

Two-way binding targets can be a plain property or a writable signal. In modern Angular you bind a signal directly: [(value)]="quantity", with no parentheses after quantity. Angular reads it for the input and calls set for you on each change.

[(ngModel)] for form controls

The most common two-way binding is ngModel, which connects a native form control to a field. It lives in FormsModule, so a standalone component must import it:

TypeScript
import { Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';

@Component({
  selector: 'app-greeter',
  imports: [FormsModule],
  template: `
    <label>
      Your name
      <input [(ngModel)]="name" />
    </label>
    <p>Hello, {{ name() }}!</p>
  `,
})
export class GreeterComponent {
  name = signal('Ada');
}

Typing in the box updates name, and the greeting changes immediately. Setting name in code (say, a "Reset" button calling name.set('')) updates the box too. ngModel works with <input>, <textarea>, <select> and checkboxes, and it is the heart of template-driven forms, a topic with its own lesson (Template-Driven Forms).

A few notes:

  • ngModel is part of the forms package, not the core. If you forget FormsModule in imports, Angular reports that ngModel is not a known property of input.
  • Inside a <form>, an ngModel control also needs a name attribute, because the form uses it to register the control.
  • For larger forms, Angular's reactive forms are usually a better fit; two-way ngModel shines for small, simple inputs such as a search box.
  • Without ngModel, you can write the same thing by hand, with no extra package: [value]="name()" (input)="name.set(box.value)" with #box on the input.

model(): two-way binding for your own components

For your own components, Angular provides model(), a signal-based input that can also write back to its parent. You declare it like an input(), but it is writable:

TypeScript
import { Component, model } from '@angular/core';

@Component({
  selector: 'app-stepper',
  template: `
    <button type="button" (click)="change(-1)" aria-label="Decrease">-</button>
    <output>{{ value() }}</output>
    <button type="button" (click)="change(1)" aria-label="Increase">+</button>
  `,
})
export class StepperComponent {
  value = model(0);

  change(delta: number): void {
    this.value.update((v) => v + delta);
  }
}

A parent uses the banana syntax:

TypeScript
@Component({
  selector: 'app-order',
  imports: [StepperComponent],
  template: `
    <app-stepper [(value)]="quantity" />
    <p>You ordered {{ quantity() }}</p>
    <button type="button" (click)="quantity.set(1)">Reset</button>
  `,
})
export class OrderComponent {
  quantity = signal(1);
}

What model(0) gives you is a ModelSignal. It acts like an input signal (you read it with value() and the parent can pass a value in) and like a writable signal (set and update exist). Every time the child calls set or update, Angular also emits the matching output, valueChange. Behind one line of code you get both the input value and the output valueChange.

Useful variants:

  • model.required<number>() makes the parent supply a value, like input.required.
  • model(0, { alias: 'count' }) changes the public name (the output becomes countChange).
  • A parent may also use only the input half ([value]="3") or only the output half ((valueChange)="log($event)").

Prefer model() for small "controlled widgets" such as steppers, toggles, tabs, ratings and date pickers, where the parent owns the value and the child changes it. For ordinary one-way data (parent to child), use input() (Inputs and Outputs).

How it desugars

Here is the data flow when the user clicks "+" in the stepper:

sequenceDiagram
  participant P as Parent (quantity signal)
  participant C as Child (value model)
  P->>C: [value]: pass quantity() down
  Note over C: user clicks +
  C->>C: value.update(v => v + 1)
  C-->>P: valueChange emits 2
  P->>P: quantity.set(2)
  P->>C: [value]: pass quantity() down again

A two-way binding is an input going down and an output coming up; the parent's signal is the source of truth.

Because the parent owns the state, a parent can also veto a change: if it listens with (valueChange)="onChange($event)" instead of the banana syntax, it decides whether to accept the new value.

A runnable stand-in of a two-way binding

The first example models the mechanism in plain TypeScript. A Signal holds a value and notifies listeners. A ModelStandIn is a child-side value that, when written to, notifies its parent. A bindTwoWay function plays the role of the compiler: it connects the parent's signal to the child's model in both directions.

TypeScript Banana in a box, desugared

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Both sides always end up equal because there is one source of truth (the parent's signal) and each change travels through it. The hand-written class is much clumsier than Angular's real ModelSignal; its job here is to make the two directions visible.

Two-way binding on a plain input, by hand

The second stand-in is an HTML page that wires a text box and a range slider to one piece of state, with no framework. Every write goes through set, and every subscriber re-renders. Type in the box, drag the slider, or press the buttons: all the views stay in sync.

One state, three views

Press "Shout": the code changes the state, and the text box updates. Type in the box: the view changes the state. That two-direction sync is what [(ngModel)] does for you.

ngModelChange: splitting the banana

[(ngModel)]="name" is shorthand for [ngModel]="name" plus (ngModelChange)="name = $event". When you write the two halves yourself, you can run extra code on every change, or transform the value before storing it:

HTML
<!-- plain two-way binding -->
<input [(ngModel)]="query" />

<!-- the same thing, split, with extra work on each change -->
<input [ngModel]="query()" (ngModelChange)="onQueryChange($event)" />
TypeScript
onQueryChange(value: string): void {
  this.query.set(value.trim().toLowerCase());
  this.page.set(1); // a new search starts at page one
}

Choose the split form whenever the new value needs validation, normalization or a side effect. Do not combine [(ngModel)] with a separate (ngModelChange) on the same input; the order in which the two handlers run is easy to get wrong.

When not to use two-way binding

Two-way binding is convenient but hides the data flow: when many parts of the page can write to a value, it gets hard to see who changed it. A good rule of thumb is to use it for simple controls where the parent really wants the child to edit its value (inputs, toggles, steppers) and to use one-way inputs with explicit outputs for everything else. The next lessons also show richer options for forms: reactive forms and signal forms.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does <app-stepper [(value)]="quantity" /> desugar to?

    Two-way binding is an input named value plus an output named valueChange. The parent passes its value down and stores whatever the child emits.
  2. 2. What must a standalone component do before it can use [(ngModel)]?

    ngModel is provided by the forms package. Without FormsModule, Angular reports that ngModel is not a known property of the element.
  3. 3. What is special about a signal created with model()?

    model() creates a writable signal that is also an input. Calling set or update on it emits the matching Change output so the parent can sync.
  4. 4. Which is the best place to use two-way binding?

    Two-way binding hides the data flow, so keep it for simple controls where the parent wants the child to edit its value.

Summary

  • [(x)]="value" is shorthand for the input [x]="value()" plus the output (xChange)="value.set($event)".
  • [(ngModel)] connects form controls to a field and needs FormsModule in standalone components.
  • model() declares a signal that is an input and a writable value; setting it emits xChange to the parent.
  • model.required() and alias work like their input() counterparts.
  • The parent's signal stays the single source of truth; use two-way binding for simple controls and plain inputs and outputs elsewhere.
  • The runnable examples are stand-ins; the Angular snippets are read-only.

Next: Control Flow: @if, @for and @switch