angular-scan

Automatically detects and highlights Angular components that are re-rendering — the Angular equivalent of react-scan.

• Yellow flash — component was checked and its DOM changed (normal re-render)
• Red flash — component was checked but its DOM did not change (unnecessary render)
• Counter badge — cumulative render count on each component host element
• Toolbar HUD — floating panel with total checks, wasted renders, and a per-component inspector

Zero overhead in production — the entire library is tree-shaken when isDevMode() returns false.

Works with both zone.js and zoneless Angular applications.

👉 Live Demo

Installation

npm install angular-scan --save-dev

Usage

Provider-based (recommended)

Add provideAngularScan() to your application providers:

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideAngularScan } from 'angular-scan';

export const appConfig: ApplicationConfig = {
  providers: [provideAngularScan()],
};

Imperative API

For micro-frontends or apps where you can't modify providers, call scan() before bootstrapApplication:

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { scan } from 'angular-scan';
import { AppComponent } from './app/app.component';
import { appConfig } from './app/app.config';

scan();
bootstrapApplication(AppComponent, appConfig);

scan() returns a teardown function:

const stop = scan();
// later...
stop(); // removes overlay and stops tracking

Options

provideAngularScan({
  enabled: true, // set false to disable entirely (default: true)
  flashDurationMs: 500, // how long the flash animation lasts in ms (default: 500)
  showBadges: true, // show render count badges on host elements (default: true)
  showToolbar: true, // show the floating toolbar HUD (default: true)
});

The same options are accepted by scan().

How it works

Angular exposes window.ng.ɵsetProfiler() in development mode — the same hook used by Angular DevTools in Chrome. angular-scan registers a profiler callback to intercept every change detection cycle:

1. ChangeDetectionStart — a MutationObserver begins recording all DOM mutations
2. ChangeDetectionSyncStart/End — gates which TemplateUpdateStart events count as real renders (excludes the dev-mode checkNoChanges pass)
3. TemplateUpdateStart — the exact component instance being checked is captured
4. ChangeDetectionEnd — MutationObserver.takeRecords() flushes synchronously; each captured instance is mapped to its host element via ng.getHostElement(); components whose subtree had DOM mutations are marked as renders, the rest as unnecessary renders

All Angular signal writes are deferred via queueMicrotask() to avoid triggering a new CD cycle from inside the profiler callback.

The canvas overlay (position: fixed, full viewport, pointer-events: none) uses a requestAnimationFrame loop to draw and fade rectangles over component host elements. The toolbar is created via createComponent() and attached to ApplicationRef outside the normal component tree, so its own renders are excluded from tracking.

Interpreting the output

| Signal | Meaning | Common cause | | -------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------- | | Yellow flash | Component re-rendered (DOM changed) | Normal update — signal/input changed | | Red flash | Component checked but DOM unchanged | Parent uses Default CD strategy; child is OnPush with no changed inputs | | High wasted count on a component | It's being checked unnecessarily on every tick | Wrap it in OnPush; ensure parent isn't Default CD | | Counter badge turns red | More unnecessary than necessary renders | Same as above — component is OnPush but still gets walked |

Requirements

• Angular ≥ 20
• Must be used in development mode (ng serve / ng build --configuration development)
• The Angular debug APIs (window.ng) are only available in dev mode — angular-scan is silently disabled otherwise