What this usually means
Zone.js monkey-patches browser APIs (setTimeout, addEventListener, Promise, etc.) to notify Angular when async tasks complete, triggering change detection. The problem isn't Zone.js itself—it's that every patched event triggers a full application-wide change detection cycle. If the component tree is large or change detection is expensive (complex bindings, heavy pipes, ngDoCheck logic), the cumulative cost of these cycles causes jank. The root cause is often an event firing at high frequency (scroll, mousemove, WebSocket messages) or a third-party library that doesn't use Angular's zone, forcing manual triggering via NgZone.run outside Angular.
The first ten minutes — establish facts before touching code.
- 1Open Chrome DevTools Performance tab, record a slow interaction, and look for long 'Animation Frame Fired' tasks followed by 'Angular Change Detection' markers.
- 2In Angular DevTools (enable debug mode in environments), run the profiler and check the 'Change Detection' tab for the per-component time spent on CD.
- 3Check the number of change detection cycles per second: run `console.log(window.angular?.getAllAngularRootElements())` and inspect `ng.probe` for component trees, but easier: add a console log in `ngDoCheck` of a root component and count calls.
- 4Identify high-frequency events: open the console, run `monkeyEvents()` from a custom snippet that logs all patched event names, or use `zone.js`'s built-in logging by setting `window.__zone_symbol__` flags.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchChrome DevTools Performance flame chart – look for 'Zone' markers and long 'Invoke' tasks
- searchAngular DevTools 'Profiler' tab – specifically the 'Change Detection' flame graph showing component-wise time
- searchAll component files that implement `ngDoCheck` or `ngAfterViewChecked` – these are often hotspots
- searchThird-party library integration files (e.g., D3 chart components, Leaflet map components) – check if they run inside Angular zone
- searchApplication-level `NgZone` usage: search for `NgZone.run` or `NgZone.runOutsideAngular` across the codebase
- searchTemplate bindings that include complex expressions or pipes – especially `async` pipes that emit frequently
Practical causes, not theory. These are the things you will actually find.
- warningMouseMove or Scroll events bound directly to component methods without debouncing, causing CD on every pixel
- warningThird-party library (e.g., Chart.js, D3) running inside Angular zone and triggering continuous CD via requestAnimationFrame or setInterval
- warningWebSocket or SSE messages updating a large component tree every few milliseconds without throttling
- warning`ngDoCheck` in a deeply nested component that manually marks the component for check (`ChangeDetectorRef.markForCheck()`) on every frame
- warningZone.js's `shouldCoalesceEventChangeDetection` not enabled, causing separate CD cycles for each async task even if they are part of the same user interaction
Concrete fix directions. Pick the one that matches your root cause.
- buildWrap high-frequency event handlers in `NgZone.runOutsideAngular()` to prevent CD, then manually trigger `ChangeDetectorRef.detectChanges()` on the specific component only when needed.
- buildEnable zone coalescing: set `Zone. __zone_symbol__` or use Angular's `provideZoneChangeDetection({ eventCoalescing: true })` to batch CD cycles for events.
- buildDebounce or throttle events (e.g., using RxJS `debounceTime`) before they reach the template or component logic.
- buildUse `OnPush` change detection strategy for components that don't need constant checks, and manually call `markForCheck()` only when data actually changes.
- buildFor third-party libraries, run their initialization inside `NgZone.runOutsideAngular`, and then use a custom service with `ChangeDetectorRef` to update specific parts of the UI.
A fix you cannot prove is a guess. Close the loop.
- verifiedRun the same interaction in Chrome DevTools Performance tab before and after the fix – compare 'Scripting' and 'Rendering' times.
- verifiedAngular DevTools profiler should show a drastic reduction in the number of change detection cycles and per-component time (e.g., from 100ms to <16ms).
- verifiedAdd a simple counter in `ngDoCheck` of a parent component; calls should drop from thousands per second to a handful.
- verifiedMonitor FPS: use `requestAnimationFrame` based counter in the console, or Chrome DevTools 'FPS' meter overlay.
Things that make this bug worse or harder to find.
- warningCalling `ChangeDetectorRef.detectChanges()` inside `NgZone.runOutsideAngular` without also calling `markForCheck()` later – you'll get ExpressionChangedAfterItHasBeenCheckedError.
- warningBlindly enabling `eventCoalescing: true` without testing – it can delay UI updates for some events (like input) causing perceived lag.
- warningOverusing `NgZone.run` to bring third-party callbacks back inside Angular – sometimes it's better to keep them outside and only update specific components.
- warningAdding `ngDoCheck` with heavy logic – it runs on every CD cycle, so keep it lightweight or avoid it entirely.
The Stuttering Dashboard: 3000 WebSocket Messages Per Second
Timeline
- 09:15Team reports live dashboard freezes for 2–3 seconds every time market data updates
- 09:20I check Angular DevTools profiler: change detection cycles at 60fps, each taking 80–120ms
- 09:30Chrome Performance tab shows long 'Invoke' tasks from Zone.js, each coinciding with WebSocket messages
- 09:45Count WebSocket messages: ~3000/sec during peak hours
- 10:00Check which components trigger CD: D3 chart component's `ngAfterViewInit` sets up D3 zoom listeners inside Angular zone
- 10:15D3 zoom listeners fire on every mouse move, each triggering change detection
- 10:30Fix: Wrap D3 setup in `NgZone.runOutsideAngular`, and only update chart data via a dedicated method that calls `ChangeDetectorRef.detectChanges()` on a container component
- 10:45Apply same pattern to WebSocket data handler: batch updates and run CD every 100ms instead of per-message
- 11:00Verify: Profiler shows CD cycles reduced to 10/sec, each under 5ms. No more freezes.
The dashboard was a real-time trading monitor. It displayed 30 D3 charts, each updating with new candlesticks every 200ms via WebSocket. Users complained about frequent stuttering. I fired up Chrome DevTools and saw the classic sign: long frames with heavy scripting time. The Angular DevTools profiler confirmed it—change detection was running nearly every animation frame, and each cycle walked through a massive component tree.
I traced the culprit to the D3 chart component. In the `ngAfterViewInit`, we called D3's `zoom()` which attaches mouse event listeners. Since those listeners were inside Angular's zone, every mouse move on the chart triggered a full change detection cycle. Combined with the 3000 WebSocket messages per second (each also triggering CD), we had a perfect storm. The solution was twofold: first, run D3's event setup outside Angular zone using `NgZone.runOutsideAngular`. Second, for WebSocket updates, I introduced a simple time-based batching using `Subject` and `debounceTime(100)`.
After the fix, the profiler showed a dramatic drop. Change detection cycles went from ~60 per second to about 10, with each cycle taking under 5ms. The stutter vanished. The key lesson: not every event needs to trigger change detection. By selectively running code outside Angular's zone and batched updates, we cut the frame time from 120ms to under 10ms. That's the difference between a frozen dashboard and a smooth one.
Root cause
D3 mouse event listeners and WebSocket messages both running inside Angular's zone, causing change detection on every mouse move and every incoming message.
The fix
Wrap D3 initialization in `NgZone.runOutsideAngular`, and batch WebSocket updates with `debounceTime(100)` inside a dedicated service that calls `ChangeDetectorRef.markForCheck()` only on the affected components.
The lesson
Always consider whether a third-party library or frequent event source needs to trigger Angular change detection. Use `NgZone.runOutsideAngular` for high-frequency events and manually control when the UI updates.
Zone.js overrides browser async APIs (setTimeout, Promise, addEventListener, etc.) to notify Angular when a task finishes. Angular then runs change detection on the entire component tree (unless using OnPush). This is fine for occasional events, but when an event fires at high frequency (e.g., mousemove, scroll, WebSocket), the cumulative cost of full tree walks becomes apparent.
The performance hit is proportional to the number of components and the complexity of their templates. A single `mousemove` event can trigger 10ms of CD on a moderately sized dashboard. At 60 events per second, that's 600ms of CD per second—guaranteed jank. The solution is to reduce the number of CD cycles or limit the scope of each cycle.
`NgZone.runOutsideAngular` executes the given function outside the Angular zone, meaning no change detection is triggered after it completes. This is ideal for high-frequency events or third-party loop mechanisms. After the work is done, you can manually trigger change detection on only the affected components via `ChangeDetectorRef.detectChanges()` or `markForCheck()`.
Example: In a component that uses D3, wrap the D3 zoom listener setup in `this.ngZone.runOutsideAngular(() => { d3.select(svg).call(zoom); })`. Later, in the D3 zoom callback, call `this.cdr.detectChanges()` on the component (or `markForCheck()` if using OnPush). This ensures UI updates only when the zoom changes, not on every mouse move.
Angular 12+ introduced zone event coalescing via `provideZoneChangeDetection({ eventCoalescing: true })`. This batches multiple async tasks that occur within the same event loop turn into a single change detection cycle. For example, a click that triggers a timer and a Promise would previously cause two CD cycles; with coalescing, it becomes one.
However, coalescing is not a silver bullet. It only batches tasks that originate from the same browser event. If you have high-frequency independent events (like mousemove), each still triggers a separate CD cycle. In those cases, debouncing or moving outside the zone is more effective. Also, coalescing can cause a slight delay in UI updates (e.g., input fields might lag), so test thoroughly.
Angular DevTools (available as a Chrome extension) provides a detailed profiler. Open it, go to the 'Profiler' tab, start recording, perform the slow interaction, then stop. The 'Change Detection' view shows a flame graph of components and how long each took. Look for components with abnormally high time—often those with complex bindings or `ngDoCheck` logic.
You can also filter by 'Change detection triggered by' to see which event (click, timeout, XHR) initiated the cycle. This helps pinpoint the source. Additionally, the 'Component tree' tab shows the number of change detection events per component. A component with a high count but low visual change is a good candidate for OnPush strategy.
Frequently asked questions
Why does Zone.js cause performance issues even when I use OnPush?
OnPush only prevents change detection if the component's input references haven't changed. But if the component or its ancestors are still in the default change detection strategy, a change detection cycle initiated by an event in the ancestor will still traverse the entire tree, including OnPush components (they just won't re-check unless marked). To fully prevent unnecessary checks, all components in the path should be OnPush, and you must avoid calling `markForCheck()` unnecessarily. Also, if a third-party library runs inside the zone and triggers CD, it doesn't respect OnPush—you must move it outside the zone.
How do I verify that an event is causing change detection?
In Chrome DevTools, open the Performance tab, start recording, trigger the event, and stop. Look for the 'Zone' markers and 'Invoke' tasks. Alternatively, add a temporary console.log inside a component's `ngDoCheck` method—if you see it logging on every event, that event is causing CD. For a more systematic approach, use Angular DevTools profiler to see which event triggered each CD cycle.
What's the difference between `detectChanges()` and `markForCheck()`?
`detectChanges()` runs change detection immediately on the component and its children, from the current component down. It's used when you need to update the view synchronously after running code outside Angular zone. `markForCheck()` schedules the component for check during the next change detection cycle (usually triggered by Zone.js). It's used with OnPush to tell Angular that the component has changed and needs re-checking. Use `markForCheck()` when you want to avoid synchronous CD and let the normal cycle handle it, but be careful not to call it too often.