Skip to content

Input Properties

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.

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.

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.
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.

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.

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.

@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 computed and effect track it directly.
  • No ngOnChanges and no SimpleChanges bag with its any-typed currentValue.
  • Required inputs are enforced at build time.
  • They participate in zoneless change detection natively.

The signal-inputs migration schematic converts an existing codebase:

Terminal window
ng generate @angular/core:signal-input-migration

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.

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.

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