Banana-Box Two-Way Binding

## Two bindings from one attribute Angular templates have two one-way bindings: `[prop]="expr"` sends a value **down** into an element or child component, and `(event)="statement"` sends a signal **up** when something happens. **Two-way binding** is not a third mechanism; it is shorthand that writes both at once: ```html <!-- what you write --> <app-volume-slider [(value)]="volume" /> <!-- what the compiler treats it as (for a plain property) --> <app-volume-slider [value]="volume" (valueChange)="volume = $event" /> ``` The rules the compiler applies: 1. The name inside `[( )]` becomes a **property binding** with the same name. 2. The same name with **`Change` appended** becomes an **event binding**. 3. The event half **assigns `$event` back** to the bound expression. If the expression is a `WritableSignal`, it calls `set($event)` instead. Because the naming convention is the whole contract, anything with a matching input and output pair can be the target: | Target | Input half | Event half | |---|---|---| | A component with `value = model(0)` | `value` | `valueChange`, created automatically by `model()` | | A component with `value = input(0)` and `valueChange = output<number>()` | `value` | `valueChange` | | `NgModel` from `FormsModule` | `ngModel` | `ngModelChange` | ## Why the order of the brackets matters The mnemonic is **"banana in a box"**: the banana-shaped parentheses go inside the box-shaped brackets, `[( )]`. The parser recognises the two-way form only by that opening `[(`. The reversed form, `([value])="volume"`, is not a syntax error. The parser sees an attribute that starts with `(`, reads it as an **event binding**, and takes the event name to be the text inside the parentheses: `[value]`. No DOM element or output ever emits an event called `[value]`, so: - the child never receives the parent's value (there is no property half at all), and - the parent never receives updates (the listener never fires). Nothing fails at runtime; the slider just does not stay in sync. With `strictTemplates` enabled, the compiler's extended diagnostic **NG8101, `invalidBananaInBox`**, reports this pattern, which is a good reason to keep strict templates on. ## What `$event` and assignment mean here The event half is an ordinary event binding, so `$event` is whatever the child's `valueChange` output emitted, typically the new number. Only the property half's expression is written to, so it must be something assignable: a field (`volume`), a nested field (`settings.volume`) or a keyed read (`levels[channel]`). A method call such as `getVolume()` or a signal read like `volume()` is rejected with *Unsupported expression in a two-way binding*, because there is nothing to assign to. ## How the compiler emits it The generated code makes the "two bindings" reading literal. For `[(value)]` the compiler emits a **two-way property instruction** in the update block and a **two-way listener** in the creation block. The property instruction behaves like any property binding: on each change detection pass it compares the new value with the one it pushed last time and only writes the child's input when they differ. The listener is registered exactly like any `(event)` listener, which means it is subject to the same rules: it marks the parent's view dirty when it runs, it is removed when the view is destroyed, and it sits in template order next to any other listener on the same element. Knowing that the pieces are ordinary bindings is what makes the edge cases predictable; nothing about `[( )]` is magic beyond the naming convention and the write-back. ## A worked example: a volume slider ```ts @Component({ selector: 'app-player', imports: [VolumeSlider], template: ` <app-volume-slider [(value)]="volume" /> <p>Volume: {{ volume() }}</p> `, }) export class Player { volume = signal(40); } ``` On each change detection pass the property half pushes `40` into the slider. When the user drags the thumb and the slider emits `valueChange` with `55`, the event half sets `volume` to `55`, and the next pass pushes `55` back down. Because the pushed value equals what the slider already shows, nothing flips back and forth. ## Common mistakes - **`([value])`**: reversed brackets; silently does nothing without strict templates. - **Expecting `[(value)]` on an element or component with no `valueChange` output**: the event half has nothing to listen to (see the input and output pair rules). - **Binding `volume()` instead of `volume`**: the template must receive the signal itself so the event half can call `set()`. - **Believing two-way binding shares one object between parent and child**: it is two one-way flows that happen to form a loop.