electron-window-glass

Native macOS window effects for Electron's BrowserWindow. Choose either public Liquid Glass or private Core Animation Backdrop.

Requirements

• macOS 14 or later for kind: 'backdrop'
• macOS Tahoe 26 or later for kind: 'glass'
• Electron 41 or later

Install

pnpm add electron-window-glass

[!TIP] Building a Vite app? vite-plugin-native-modules handles electron-window-glass automatically.

Interactive Example

Run the transparent Electron control panel without cloning the repository:

npx -y electron-window-glass@latest example

Use

Liquid Glass

Create a transparent window before attaching glass. A frameless window is a common choice, but it is not required by this package.

import { BrowserWindow } from 'electron'
import { createWindowGlass } from 'electron-window-glass'

const window = new BrowserWindow({
  backgroundColor: '#00000000',
  frame: false,
  roundedCorners: false,
  transparent: true,
})

const glass = createWindowGlass(window, {
  kind: 'glass',
  cornerRadius: 14,
  style: 'regular',
  tintColor: '#7FA8FF20',
})

glass.setStyle('clear')

The selected radius also clips Electron's native content host so renderer content cannot spill past the effect's outline. On macOS versions earlier than 26, requesting kind: 'glass' throws.

Backdrop

Use kind: 'backdrop' to opt into backdrop effect engine and its custom controls:

const backdrop = createWindowGlass(window, {
  kind: 'backdrop',
  blurRadius: 40,
  cornerCurve: 'continuous',
  cornerRadius: 14,
  gradientMaskEndX: 0.65,
  noise: { intensity: 0.05, opacity: 0.025 },
  saturation: 1.8,
})

createWindowGlass waits for a usable native handle when necessary and disposes itself when the window closes. The backdrop renderer also reapplies its WindowServer tags after Electron’s resized event. Call glass.dispose() when removing an effect before the window closes. Disposal is idempotent.

For low-level integrations, createWindowGlass(window.getNativeWindowHandle(), options) returns a WindowGlass instance. Prefer the BrowserWindow overload: it is the only API that manages readiness, resize tag reapplication, and automatic cleanup.

Renderers and Runtime Controls

The second argument is a discriminated union based on kind:

• GlassOptions → kind: 'glass'
• BackdropOptions → kind: 'backdrop'

This keeps renderer-specific options type-safe and prevents backdrop-only controls from being passed to the native system glass renderer.

glass

| Options | Runtime controls | | -------------- | ----------------- | | alpha | setAlpha | | cornerRadius | setCornerRadius | | style | setStyle | | tintColor | setTintColor |

backdrop

| Options | Runtime controls | | ------------------ | ----------------- | | alpha | setAlpha | | blurRadius | setBlurRadius | | cornerCurve | setCornerCurve | | cornerRadius | setCornerRadius | | gradientMaskEndX | setGradientMask | | noise | setNoise | | saturation | setSaturation |

Important Limitations

The backdrop renderer dynamically uses private Core Animation and WindowServer symbols, including CABackdropLayer, CAFilter, and CGS window tags. Apple can change or remove these without notice; an Electron or macOS update can alter the visual result, break the effect, or cause instability. It is not suitable for Mac App Store distribution.

License

MIT