electron-overlay-dimming

name	electron-overlay-dimming
description	Reusable pattern for focus-based auto-dimming of Electron overlay windows — when the app loses focus, all overlay windows fade to a low opacity; when an overlay regains focus, they return to their configured opacity. Use when building always-on-top Electron overlays that should recede while the user works in other apps.

Electron Overlay Auto-Dimming

A small, self-contained pattern for always-on-top Electron overlays: the overlays stay readable while in use but fade out of the way when the user clicks into another application, and restore when focus returns to an overlay. First shipped in the benchmark-overlay app.

Behaviour

• App loses focus (no overlay window is focused) → every overlay window's opacity drops to a dim level (~0.2).
• Focus returns to any overlay → every overlay restores to its configured opacity (not blindly to 1.0 — it respects any per-overlay opacity the user set).

Why it's not naive

Two pitfalls the pattern handles:

1. Inter-overlay clicks. Clicking from overlay A to overlay B fires a blur then a focus. Dimming on raw blur would flicker. The fix: on blur, defer ~80 ms and only dim if BrowserWindow.getFocusedWindow() is then null — i.e. the app truly lost focus, not just one window.
2. Configured opacity. Overlays may each have a user-set base opacity. Auto-dim must dim from and restore to that value, so opacity is always computed as appDimmed ? DIM_OPACITY : overlay.config.opacity.

Reference implementation (main process)

const DIM_OPACITY = 0.2;
let appDimmed = false;

function effectiveOpacity(o) {
  return appDimmed ? DIM_OPACITY : o.config.opacity;
}

function applyOpacityAll() {
  for (const o of Object.values(OVERLAYS)) {
    if (o.win && !o.win.isDestroyed()) o.win.setOpacity(effectiveOpacity(o));
  }
}

app.on('browser-window-focus', () => {
  if (appDimmed) { appDimmed = false; applyOpacityAll(); }
});

app.on('browser-window-blur', () => {
  // Defer so an A→B overlay click doesn't briefly dim.
  setTimeout(() => {
    if (!appDimmed && !BrowserWindow.getFocusedWindow()) {
      appDimmed = true;
      applyOpacityAll();
    }
  }, 80);
});

Any code path that sets a window's opacity (e.g. a config handler) must route through effectiveOpacity() so opacity changes made while dimmed don't undim the window.

Reference app

Live implementation: ~/projects/benchmark-overlay/main.js — the benchmark-overlay app applies this across three overlay windows (AI Benchmarks, System Resources, Hub Overlay).