OnPush Change Detection
Helps improve Angular rendering performance by applying ChangeDetectionStrategy.OnPush only when component data flow supports it.
SKILL.mdskills/angular/performance/onpush-change-detection/SKILL.md
GitHubOnPush Change Detection
Purpose
Use this skill to improve Angular rendering performance by applying ChangeDetectionStrategy.OnPush safely and intentionally. The goal is to reduce unnecessary checks without hiding state mutation bugs or breaking view updates.
This skill is complementary to change-detection-optimization; keep it focused on explicit OnPush adoption and mutation safety.
When to Use
Use this skill when:
- A component renders frequently without visible data changes.
- The component receives most data through inputs, observables, or signals.
- A performance task mentions change detection, slow rendering, or heavy templates.
- A component can be updated through immutable state changes.
- The current code already has tests or clear rendering behavior to verify.
- The project can prove the state flow before introducing OnPush.
Do
Prefer OnPush when the component has explicit data flow and immutable updates:
@Component({
selector: "app-user-card",
templateUrl: "./user-card.component.html",
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class UserCardComponent {
@Input({ required: true }) user!: UserViewModel;
}
Prefer replacing object mutation with new references:
this.user = {
...this.user,
displayName: nextDisplayName,
};
For asynchronous data, prefer template subscriptions with async or state exposed through signals:
<app-user-card [user]="user$ | async" />
readonly fullName = computed(() => {
const user = this.user();
return `${user.firstName} ${user.lastName}`;
});
Use markForCheck only when an external callback updates state outside Angular's normal path and the component still needs the view refreshed.
Do Not
Avoid applying OnPush blindly:
@Component({
selector: "app-user-editor",
templateUrl: "./user-editor.component.html",
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class UserEditorComponent {
@Input() user!: User;
rename(value: string): void {
this.user.name = value;
}
}
Avoid using OnPush as a cosmetic change when the component relies on hidden side effects, mutable shared objects, or untracked state changes.
Avoid turning unrelated services, global stores, or routing state into an OnPush justification if the real issue is elsewhere.
Review Checklist
-
OnPushis applied only where the component data flow is explicit. - Inputs are not mutated directly.
- Arrays and objects are replaced immutably when their visible state changes.
- Observables are consumed with
async, signals, or explicit lifecycle-safe subscriptions. - Signals use
set,update, or computed values instead of hidden mutation. - Forms, overlays, timers, and imperative callbacks still update the view correctly.
- Tests or manual verification cover the affected rendering path.
Expected Output
- Inspect the component data flow before adding
OnPush. - Identify mutation or side-effect risks.
- Apply the smallest safe change needed for rendering performance.
- Preserve existing behavior and avoid broad architecture rewrites.
- Add or update tests when rendering behavior changes.