Input Properties
What inputs are
Section titled “What inputs are”An input declares the data a component accepts from its parent. Modern Angular declares them with the input() function, which returns a signal:
import { Component, input, computed } from '@angular/core';
@Component({ selector: 'custom-slider', /* ... */ })export class CustomSlider { readonly value = input(0); readonly label = computed(() => `The slider's value is ${this.value()}`);}<custom-slider [value]="50" />Signal inputs are the reason computed works so cleanly on component data: an input is a signal, so anything derived from it recomputes automatically, and templates reading it are marked dirty precisely when it changes.
Four rules the compiler enforces, worth knowing up front:
- Inputs are recorded statically at compile time. They cannot be added or removed at runtime.
input()may only be called in component and directive property initialisers. It has special meaning to the compiler.- Inputs are inherited by a subclass.
- Input names are case-sensitive.
Types and required inputs
Section titled “Types and required inputs”TypeScript infers the type from the default value:
readonly value = input(0); // InputSignal<number>Without a default, an unset input is undefined, and the type reflects that:
readonly value = input<number>(); // InputSignal<number | undefined>input.required makes the input mandatory — Angular reports a build-time error if a template uses the component without it — and the resulting type does not include undefined:
readonly value = input.required<number>(); // InputSignal<number>Use input.required whenever a component genuinely cannot function without the value. It moves a runtime “cannot read property of undefined” to a compile error, which is a large win for a one-word change.
The signal returned by input() is read-only. A component cannot write to its own input — which is a feature, since inputs are the parent’s data.
Transforms
Section titled “Transforms”A transform function converts the value as Angular sets it:
readonly label = input('', { transform: trimString });
function trimString(value: string | undefined): string { return value?.trim() ?? '';}The most common purpose is accepting a wider range of types in templates — often including null and undefined — while presenting a narrow, clean type inside the component. Note that the transform’s parameter type determines what a template may bind, while the InputSignal reports the return type:
readonly widthPx = input('', { transform: appendPx }); // accepts number, reads string
function appendPx(value: number): string { return `${value}px`;}Two constraints:
- The transform must be statically analysable at build time. It cannot be chosen conditionally or produced by an expression.
- Transforms must be pure. Depending on state outside the function produces unpredictable behaviour, because the transform runs whenever the bound value changes and nothing else invalidates it.
Built-in transforms
Section titled “Built-in transforms”import { booleanAttribute, numberAttribute } from '@angular/core';
readonly disabled = input(false, { transform: booleanAttribute });readonly value = input(0, { transform: numberAttribute });booleanAttribute mirrors HTML boolean-attribute semantics — presence means true — with one Angular-specific refinement: the literal string "false" is treated as false. That makes <custom-slider disabled> and <custom-slider disabled="false"> both behave the way a reader expects, which the raw HTML rule would not.
numberAttribute parses to a number and yields NaN on failure. Guard for NaN if the value drives anything arithmetic — it propagates silently.
Aliases
Section titled “Aliases”readonly value = input(0, { alias: 'sliderValue' });<custom-slider [sliderValue]="50" />The alias changes only the template name; TypeScript still uses the property name.
Generally avoid aliasing on components — two names for one thing is a cost every future reader pays. The legitimate uses are renaming a property while keeping the old name working during a deprecation, and avoiding a collision with a native DOM property name.
Model inputs
Section titled “Model inputs”A model() is an input a component can write to, propagating the new value back through a two-way binding:
@Component({ selector: 'custom-slider', /* ... */ })export class CustomSlider { readonly value = model(0);
increment(): void { this.value.update((v) => v + 10); }}<custom-slider [(value)]="volume" />model() is the signal-era replacement for the @Input() x / @Output() xChange pair — it generates the output automatically, so [(value)] works without you writing a valueChange emitter.
Use it for genuine two-way controls: a slider, a toggle, a date picker, a custom form control. Do not use it as a shortcut for state that really belongs to the parent — a model() that both sides write to is two sources of truth, and the resulting “who set this last” bugs are unpleasant. If only the parent should own the value, use input() plus an output() and let the parent decide what to do.
The decorator API
Section titled “The decorator API”@Input() value = 0;@Input({ required: true }) id!: string;@Input({ transform: booleanAttribute }) disabled = false;@Input() still works and is not going away imminently, but signal inputs are the modern API and are better in ways that matter:
- The value is a signal, so
computedandeffecttrack it directly. - No
ngOnChangesand noSimpleChangesbag with itsany-typedcurrentValue. - Required inputs are enforced at build time.
- They participate in zoneless change detection natively.
The signal-inputs migration schematic converts an existing codebase:
ng generate @angular/core:signal-input-migrationReacting to input changes
Section titled “Reacting to input changes”With @Input(), reacting meant a setter or ngOnChanges:
@Input() set userId(value: string) { this.loadUser(value); // runs on every set, ordering unclear}With signal inputs, derive instead:
readonly userId = input.required<string>();readonly user = httpResource<User>(() => `/api/users/${this.userId()}`);That is the important shift. An input setter is imperative and runs at a moment you do not fully control; a computed or a resource is declarative and recomputes when — and only when — the value actually changed. Reach for effect only when the destination is genuinely not a signal.
Inputs and change detection
Section titled “Inputs and change detection”Under OnPush (the default from v22), a component is checked when it receives a new input as the result of a template binding, and Angular compares previous and current values with ==.
Two consequences that account for a lot of “my child doesn’t update”:
Mutating an object without changing the reference does nothing. this.order.lines.push(line) leaves the input == to what it was. Replace the reference, or hold the data in a signal the child reads.
Object and array literals in bindings do the opposite. [config]="{ dense: true }" creates a new object on every check, so the comparison is always false and the child is refreshed forever. Hoist the literal to a field or a computed.
Setting an input imperatively bypasses the binding path entirely. Reaching a child through viewChild() and assigning to its input notifies nothing. Use ComponentRef.setInput() for programmatically created components, or restructure so the value flows through a binding.
Common mistakes
Section titled “Common mistakes”| Mistake | Consequence | Fix |
|---|---|---|
| Optional input for a mandatory value | Runtime undefined errors |
input.required |
| Mutating an object passed as an input | Child never refreshes under OnPush |
Replace the reference or use signals |
| Object/array literal in a binding | Child refreshes on every check | Hoist to a field or computed |
| Input setter for derived state | Imperative, order-dependent, easy to get stale | computed from the signal input |
| Impure or conditional transform | Unpredictable; fails to compile | Pure, statically analysable functions |
numberAttribute result used unguarded |
NaN propagates silently |
Check for NaN |
| Aliasing without a reason | Two names for one concept | Only for deprecation or DOM collisions |
model() where input() + output() was right |
Two writers, ambiguous ownership | model() only for genuine two-way controls |
Assigning to a child’s input via viewChild |
No change notification | ComponentRef.setInput() or a real binding |
input() outside a property initialiser |
Compile error | It is only valid there |
Related pages
Section titled “Related pages”- Signals and Angular Reactivity
- Change Detection and Zoneless Angular
- ContentChild and Content Projection
- Host Binding and Host Listening
- Component basics