electron-liquid-glass

npm
npm downloads
GitHub

Node

Modern macOS glass effects for Electron applications

🪄 NATIVE NSGlassEffectView integration with ZERO CSS hacks

Installation • Quick Start • API • Examples • Contributing

</div>

✨ Features

🪟 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

🚀 Installation

bash
# npm
npm install electron-liquid-glass

# yarn
yarn add electron-liquid-glass

# pnpm
pnpm add electron-liquid-glass

# bun
bun add electron-liquid-glass

Requirements

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.

🎯 Quick Start

Basic Usage

javascript
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);
  });
});

TypeScript Usage

typescript
import { BrowserWindow } from "electron";
import liquidGlass, { GlassOptions } from "electron-liquid-glass";

const options: GlassOptions = {
  cornerRadius: 16, // (optional)
  tintColor: "#44000010", // black tint (optional)
  opaque: true, // add opaque background behind glass (optional)
};

liquidGlass.addView(window.getNativeWindowHandle(), options);

📚 API Reference

`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

`GlassOptions`

typescript
interface GlassOptions {
  cornerRadius?: number; // Corner radius in pixels (default: 0)
  tintColor?: string; // Hex color with optional alpha (#RRGGBB or #RRGGBBAA)
  opaque?: boolean; // Add opaque background behind glass (default: false)
}

UNDOCUMENTED EXPERIMENTAL METHODS

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

typescript
// 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);

🔧 Development

Building from Source

bash
# 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:

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

Project Structure

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

🏗️ How It Works

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