electron-liquid-glass: Electron bindings for Apple Liquid Glass

4 hours ago 1

🪟 Native Glass Effects - Real NSGlassEffectView integration, not CSS approximations
⚡ Zero Configuration - Works out of the box with any Electron app
🎨 Fully Customizable - Corner radius, tint colors, and glass variants
📦 Modern Package - Dual ESM/CommonJS support with TypeScript declarations
🔧 Pre-built Binaries - No compilation required for standard setups
🌙 Auto Dark Mode - Automatically adapts to system appearance changes

# npm npm install electron-liquid-glass # yarn yarn add electron-liquid-glass # pnpm pnpm add electron-liquid-glass # bun bun add electron-liquid-glass

macOS 26+ (Tahoe or later)
Electron 30+
Node.js 22+

Note: This package only works on macOS. On other platforms, it provides safe no-op fallbacks.

import { app, BrowserWindow } from "electron"; import liquidGlass from "electron-liquid-glass"; app.whenReady().then(() => { const win = new BrowserWindow({ width: 800, height: 600, vibrancy: false, // <-- ❌❌❌ do NOT set vibrancy alongside with liquid glass, it will override and look blurry transparent: true, // <-- This MUST be true }); win.setWindowButtonVisibility(true); // <-- ✅ This is required to show the window buttons win.loadFile("index.html"); /** * 🪄 Apply glass effect after content loads 🪄 */ win.webContents.once("did-finish-load", () => { // 🪄 Apply effect, get handle const glassId = liquidGlass.addView(win.getNativeWindowHandle(), { /* options */ }); // Experimental, undocumented private APIs liquidGlass.unstable_setVariant(glassId, 2); }); });

import { BrowserWindow } from "electron"; import liquidGlass, { GlassOptions } from "electron-liquid-glass"; const options: GlassOptions = { cornerRadius: 16, // (optional) tintColor: "#44000010", // black tint (optional) }; liquidGlass.addView(window.getNativeWindowHandle(), options);

liquidGlass.addView(handle, options?)

Applies a glass effect to an Electron window.

Parameters:

handle: Buffer - The native window handle from BrowserWindow.getNativeWindowHandle()
options?: GlassOptions - Configuration options

Returns: number - A unique view ID for future operations

interface GlassOptions { cornerRadius?: number; // Corner radius in pixels (default: 0) tintColor?: string; // Hex color with optional alpha (#RRGGBB or #RRGGBBAA) }

UNDOCUMENTED EXPERIMENTAL METHODS

⚠️ Warning: DO NOT USE IN PROD. These methods use private macOS APIs and may change in future versions.

// Glass variants (number) (0-15, 19 are functional) liquidGlass.unstable_setVariant(glassId, 2); // Scrim overlay (0 = off, 1 = on) liquidGlass.unstable_setScrim(glassId, 1); // Subdued state (0 = normal, 1 = subdued) liquidGlass.unstable_setSubdued(glassId, 1);

# Clone the repository git clone https://github.com/meridius-labs/electron-liquid-glass.git cd electron-liquid-glass # Install dependencies bun install # Build native module bun run build:native # Build TypeScript library bun run build # Build everything bun run build:all

Rebuilding for Custom Electron

If you're using a custom Electron version:

npx electron-rebuild -f -w electron-liquid-glass

electron-liquid-glass/ ├── src/ # Native C++ source code │ ├── glass_effect.mm # Objective-C++ implementation │ └── liquidglass.cc # Node.js addon bindings ├── js/ # TypeScript source │ ├── index.ts # Main library code │ └── native-loader.ts # Native module loader ├── dist/ # Built library (generated) ├── examples/ # Example applications └── prebuilds/ # Pre-built binaries

Native Integration: Uses Objective-C++ to create NSGlassEffectView instances
View Hierarchy: Inserts glass views behind your web content, not over it
Automatic Updates: Listens for system appearance changes to keep effects in sync
Memory Management: Properly manages native view lifecycle

Primary: Uses private NSGlassEffectView API when available
Fallback: Falls back to public NSVisualEffectView on older systems
Performance: Minimal overhead, native rendering performance
Compatibility: Works with all Electron window configurations

We welcome contributions! Please see our Contributing Guide for details.