RFC: Signal-based inputs

[rkaraivanov]

Summary

This RFC proposes how Ignite UI for Angular moves its component inputs from the @Input() decorator to Angular signals. The library has 1,007 @Input() declarations in 364 components and directives. Two migrations are done: the button directives (#17155) and the checkbox, switch and radio components (#17604). Both keep the public API and put a signal() behind each accessor. This RFC compares that pattern with the Angular input() and model() APIs and recommends a path.

Answer the numbered questions in the last section. Quote the question number in your reply.

Motivation

Signals are the reactive model of Angular. State that lives in signals makes OnPush and zoneless change detection safe. A plain @Input() field is a property with no setter. A template binding writes it during the parent's change detection, marks the child view dirty and calls ngOnChanges. A direct write from TypeScript, ref.checked = true, does none of that. Angular does not observe the property. With Zone.js and Default change detection, every async task scheduled a pass that re-read the field, so the write was picked up. An OnPush component is refreshed only when it is marked dirty. A zoneless application runs a pass only when Angular is notified: a signal write, markForCheck(), a template event listener, an input binding or setInput(). A direct write from a setTimeout, a third-party callback or a method that consumer code calls does not repaint. ngDoCheck and ChangeDetectionStrategy.Eager still exist in zoneless. They run only inside a pass that something else scheduled, and they cost CPU on every pass.

The library needs signal-backed inputs for three reasons:

• Zoneless support. Angular runs without Zone.js by default for new applications. A component that depends on zone-triggered checks does not update.
• Performance. OnPush components are checked only when a signal they read changes, an input binding changes or an event fires. The radio group used ngDoCheck to sync tabindex on every pass before refactor(checkbox,switch,radio): migrate to signals and OnPush #17604.
• Derived state. computed() memoizes values such as host classes and ARIA attributes. Host bindings read signals directly. Renderer2 writes and @HostBinding members are not necessary.

The goal of this RFC is to pick one pattern for the 1,007 remaining @Input() declarations. The pattern must be applied consistently so that consumers learn one rule.

Current state

The library uses three patterns today.

Pattern 1: @Input() on a plain field. This is the legacy pattern. It covers most of the 1,007 @Input() declarations. The field does not notify change detection.

Pattern 2: @Input() on an accessor, backed by a signal(). The button directives (#17155) and the checkbox, switch and radio components (#17604) use this pattern. The public API does not change. Host bindings and templates read the backing signal.

protected readonly _selected = signal(false);

@Input({ transform: booleanAttribute })
public set selected(value: boolean) {
    this._selected.set(value);
}
public get selected(): boolean {
    return this._selected();
}

Pattern 3: input() and model(). New components use the signal APIs directly. IgxGridLiteComponent declares data and autoGenerate with input() and sortingExpressions with model(). IgxVirtualScrollRecycleDirective uses input.required(). 42 files use input() today.

public readonly data = input<T[]>([]);
public readonly sortingExpressions = model<IgxGridLiteSortingExpression<T>[]>([]);

The library also writes to inputs of other components from TypeScript. IgxButtonGroupComponent sets button.disabled. IgxRadioGroupDirective sets button.name, button.required and button.checked. Specs assign component properties directly in about 1,600 places. Neither compiles against a read-only input() signal.

Constraints

Each option must satisfy these constraints, or the RFC must say which one it breaks.

1. Template bindings do not change. [checked]="x" and checked="true" must work in all options. Angular binds @Input(), input() and model() the same way from a template.
2. Imperative writes exist. Consumers hold references through @ViewChild and viewChild() and write ref.checked = true in event handlers and methods. Angular input() signals are read-only. Angular documents one write path for them: a template binding, inputBinding() at creation or ComponentRef.setInput().
3. Imperative reads exist. ref.checked is a value today. With a signal it is a function, ref.checked().
4. Transforms exist. 244 inputs use booleanAttribute or a custom transform. model() does not support transforms. An attribute without a binding then arrives as an empty string.
5. Inheritance exists. Base directives such as CheckboxBaseDirective declare inputs that subclasses override. A subclass cannot re-declare an inherited input() with a different transform or type. The compiler rejects it with TS2416.
6. Setters have side effects. The checked setter calls the ControlValueAccessor change callback. A signal input has no setter. Side effects move to effect() or to the write site.
7. Specs write properties directly. About 1,600 assignments in 277 spec files set component properties. A read-only signal needs fixture.componentRef.setInput() instead.
8. Bundle size matters. Each pattern costs a different number of bytes per input. The Comparison section gives the numbers.
9. Tooling. The API docs come from TypeDoc. The Angular signal-input-migration schematic skips accessor inputs and inputs that are written to. A consumer-facing break needs an ng update migration in projects/igniteui-angular/migrations.
10. Release policy. Breaking changes ship only in a major version with a changelog entry and a migration.

Options

Six options are possible. Options A, D and E keep the public API. Options B, C and F change it.

Option A: @Input() accessor over a signal()

This is the pattern of #17155 and #17604.

protected readonly _checked = signal(false);

@Input({ transform: booleanAttribute })
public set checked(value: boolean) {
    this._checked.set(value);
}
public get checked(): boolean {
    return this._checked();
}

Pros:

• No public API change. Reads, writes, template bindings and specs stay as they are.
• Transforms, required, inheritance overrides and setter side effects work.
• Ships in a minor version.
• A later move to input() or model() needs no design work. The backing signal already exists.

Cons:

• Twice the bytes of a plain @Input() field. 1.8 times the bytes of input().
• Two names for one state: checked for consumers, _checked() for templates and host bindings.
• Consumers get no signal. They cannot build computed() or effect() on component state.
• Eight lines of code per input.
• The Angular signal-input-migration schematic skips accessor inputs. A later conversion needs our own schematic.

Option B: input() for every input

public readonly checked = input(false, { transform: booleanAttribute });

Pros:

• The API the Angular team recommends for new code.
• The smallest signal-based cost per input.
• Consumers get a signal: computed(() => checkbox.checked()).
• input.required() reports a missing binding at compile time.
• Angular supplies a migration schematic for the library source.

Cons:

• Breaking. ref.checked = true does not compile. In JavaScript, or through any, the assignment replaces the signal with a boolean and the template throws at the next render.
• Every read changes from ref.checked to ref.checked().
• The only write path from TypeScript is ComponentRef.setInput(). A @ViewChild gives an instance, not a ComponentRef.
• Writes between library components need a redesign. The radio group pushes name, required and checked into each radio. The radios must derive these values from the group through DI and computed().
• A subclass cannot override an inherited input with a different transform or type (TS2416).
• Setter side effects move to effect(). An effect runs during change detection, not at the time of the write.
• Specs replace about 1,600 property writes with componentRef.setInput().
• Ships only in a major version. A schematic can rewrite typed reads to ref.checked(). It cannot rewrite writes. The consumer must restructure the code.

Option C: model() for state, input() for configuration

// State: the consumer and the component write it.
public readonly checked = model(false);

// Configuration: only the consumer sets it.
public readonly labelPosition = input<LabelPosition>('after');

Pros:

• Writable from anywhere: ref.checked.set(true).
• Two-way binding [(checked)] without extra code. The 44 existing x and xChange pairs in 26 files map directly to model().
• Consumers get a signal.
• A schematic can rewrite ref.x = v to ref.x.set(v).

Cons:

• Breaking. Reads and writes change syntax, as in Option B.
• No transforms. <igx-checkbox checked> binds the empty string. 244 inputs use a transform today. A linkedSignal() that coerces the value adds bytes and a second name.
• model() emits xChange on every set(), also on programmatic writes. Existing xChange outputs emit on user interaction only. The event contract changes.
• The inheritance limit of Option B applies.
• Each input needs a decision: state or configuration. Reviewers must apply one rule.

Option D: Option A plus a public read-only signal

protected readonly _checked = signal(false);
public readonly checkedSignal = this._checked.asReadonly();

@Input({ transform: booleanAttribute })
public set checked(value: boolean) { this._checked.set(value); }
public get checked(): boolean { return this._checked(); }

Pros:

• Not breaking. Consumers get reactivity now.

Cons:

• The most bytes per input.
• Two public names for one state. The API surface doubles.
• A later move to input() leaves the second name as dead API or causes a second break.

Option E: Generated accessors with inputs metadata

@Directive({ inputs: [{ name: 'checked', transform: booleanAttribute }] })
export class IgxCheckboxComponent {
    protected readonly _checked = signal(false);
    declare public checked: boolean;
}
defineSignalInputs(IgxCheckboxComponent, ['checked']);

A shared helper defines one accessor pair per name on the prototype.

Pros:

• Not breaking. Less source code per input than Option A.
• Fewer bytes than Option A when a class has many inputs. The helper cost is fixed.

Cons:

• Hidden control flow. declare fields have no body. IDE navigation and TypeDoc point to an empty declaration.
• The top-level call is a module side effect. The repository lint rule no-inputs-metadata-property forbids the inputs array.
• Not idiomatic Angular. Contributors must learn a mechanism that exists only in this repository.

Option E is rejected. The comparison lists it for completeness.

Option F: input() plus linkedSignal()

public readonly checkedInput = input(false, { alias: 'checked', transform: booleanAttribute });
public readonly checked = linkedSignal(this.checkedInput);

The template binds [checked]. TypeScript reads ref.checked() and writes ref.checked.set(true). A new bound value replaces the local write.

Pros:

• Writable from anywhere, with transforms. No implicit xChange output.
• Consumers get a signal.
• A schematic can rewrite ref.x = v to ref.x.set(v).

Cons:

• Breaking. Reads and writes change syntax, as in Option B.
• Two public members per input. The alias hides checkedInput in templates, not in the API docs.
• More bytes per input than Option A.
• A binding update discards an imperative write without a warning. Consumers must learn this rule.
• The inheritance limit of Option B applies.

Comparison

Option	Public API break	Bytes per input, minified	Bytes per input, gzip	Imperative write	Consumer gets a signal	Transforms	Subclass override	Ships in
Today: @Input() field	No	74	33	ref.x = v	No	Yes	Yes	Minor
A: accessor over signal()	No	155	54	ref.x = v	No	Yes	Yes	Minor
B: input()	Yes	86	38	ComponentRef.setInput() only	Yes	Yes	No (TS2416)	Major
C: model() + input()	Yes	101 / 86	41 / 38	ref.x.set(v) for model()	Yes	input() only	No (TS2416)	Major
D: A + read-only signal	No	200	63	ref.x = v	Yes, under a second name	Yes	Yes	Minor
E: generated accessors	No	131	61	ref.x = v	No	Yes	Possible	Minor
F: input() + linkedSignal()	Yes	163	56	ref.x.set(v)	Yes	Yes	No (TS2416)	Major

Over 1,007 inputs, Option A costs about 69 KB minified and 16 KB gzipped more than Option B. An application pays only for the components it imports. Option C has two values per cell: model() first, input() second.

Measurement method

A directive with five inputs, compiled with ngc 22.2.0 in full compilation mode, minified with esbuild 0.28.2, ngDevMode set to false. Per-input bytes are the difference to an empty directive divided by five. Measured 2026-10-12.

Recommendation

Adopt Option A for all existing inputs now. Move the public API to Option C or Option F in a later major release, after a separate decision.

Option A is the only option that satisfies constraints 2 to 7 and 10 without a major release. The byte cost is known. Options B, C and F break every consumer that reads or writes an input from TypeScript. That break is acceptable once, with a schematic, in a major release.

Rules for Option A

1. One class, one pattern. A class uses either @Input() accessors or input()/model(). Do not mix.
2. New components with no decorator inputs use input() and model(), as IgxGridLiteComponent does.
3. The backing signal is protected readonly _name. Templates and host bindings read _name().
4. Derived values are computed(). Host bindings live in host metadata. @HostBinding and Renderer2 writes are removed.
5. A setter that calls a callback wraps the call in untracked().
6. A component switches to OnPush in the same PR that makes all its state signal-backed.
7. The PR removes only @hidden @internal members. Every removal has a changelog entry.

Migration plan

1. 22.x minors. Convert components in dependency order: base directives, then leaf components, then grids. One PR per component family. Done: button, checkbox, switch, radio.
2. 23.0. No input API change. All components are signal-backed and OnPush.
3. Before the switch. Write a schematic that converts an accessor pair to input() or model() from a per-input list. Decide state or configuration for each input. Validate on the demo application and the specs.
4. Major release, proposed 24.0. Ship Option C or Option F with an ng update migration. The migration rewrites ref.x to ref.x() and ref.x = v to ref.x.set(v) where x is a model(). It inserts a TODO where x is an input().

Step 4 needs its own RFC. This RFC decides steps 1 to 3.

Open questions

1. Do we accept the byte cost of Option A until the major release? See the comparison table.
2. Which major release carries the public switch? The proposal says 24.0.
3. Option C or Option F for the switch? Option C gives two-way binding and xChange outputs. Option F keeps transforms and costs more bytes.
4. What is the rule for state versus configuration? Proposal: an input is state when user interaction or the component changes it, or when an xChange output exists. All other inputs are configuration.
5. Do we expose a read-only signal (Option D) for a short list of inputs, such as grid data, before the switch? Proposal: no.
6. Do we file an upstream request for model() transforms before step 4? Without transforms, 244 inputs lose attribute coercion.
7. Does the xChange contract change when model() emits on programmatic writes? Proposal: document it as a breaking change in step 4.

References

• Angular: Accepting data with input properties. Signal inputs are read-only. model() does not support transforms. @Input remains fully supported.
• Angular: model() API.
• Angular: Migration to signal inputs. The schematic skips inputs that cannot be migrated safely.
• Angular: Programmatically rendering components. inputBinding(), twoWayBinding() and ComponentRef.setInput().
• angular/angular#59135. The schematic and re-assigned inputs.
• refactor(button): Migrate to signal backed state management #17155: Migrate button to signal-backed state.
• refactor(checkbox,switch,radio): migrate to signals and OnPush #17604: Migrate checkbox, switch and radio to signals and OnPush.

[kdinev]

@rkaraivanov I would personally migrate apps I've created with igniteui-angular through a breaking change, in order to not have the cons (increase in bundle size) of Option A, but that's just me. My assumption would be most people would go for Option A, because it does not introduce a breaking change, even though it's at the cost of (not a significant) bundle-size increase.

What would be the difference to me, as a consumer, between Option C and Option F?