electron-liquid-glass

The library provides native macOS glass effects by integrating directly with the system's view hierarchy.

Core Mechanisms

• Native Integration: Uses Objective-C++ to create NSGlassEffectView instances.
• View Hierarchy: Instead of overlaying content, it inserts glass views behind your web content.
• Automatic Updates: The library listens for system appearance changes (e.g., switching between Light and Dark mode) to keep the glass effect in sync with the OS.
• Fallback Behavior: It uses the private NSGlassEffectView API when available, falling back to the public NSVisualEffectView on older systems.
• Memory Management: It handles the native view lifecycle to prevent memory leaks.

Install the package using your preferred package manager. Note that this package only works on macOS; on other platforms, it provides safe no-op fallbacks.

Requirements

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

# npm
npm install electron-liquid-glass

# yarn
yarn add electron-liquid-glass

# pnpm
pnpm add electron-liquid-glass

# bun
bun add electron-liquid-glass

When using TypeScript, you can import the GlassOptions type to ensure type safety when configuring your glass effect.

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

const options: GlassOptions = {
  cornerRadius: 16,
  tintColor: "#44000010",
  opaque: true,
};

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

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

Applies a native glass effect to an Electron window.

Signature: liquidGlass.addView(handle, options?)

Parameters:

• handle: Buffer - The native window handle obtained via BrowserWindow.getNativeWindowHandle().
• options?: GlassOptions - Configuration object for the effect.

Returns: number - A unique view ID used for subsequent operations on this specific glass view.

liquidGlass.addView(handle: Buffer, options?: GlassOptions): number

⚠️ WARNING: DO NOT USE IN PRODUCTION. These methods use private macOS APIs and are subject to change without notice.

Use these methods with the glassId returned by addView().

• unstable_setVariant(glassId, variant: number): Sets the glass variant (0-15, 19 are functional).
• unstable_setScrim(glassId, state: number): Toggles the scrim overlay (0 = off, 1 = on).
• unstable_setSubdued(glassId, state: number): Toggles the subdued state (0 = normal, 1 = subdued).

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

Configuration object for defining the appearance of the glass effect.

interface GlassOptions {
  cornerRadius?: number;
  tintColor?: string;
  opaque?: boolean;
}

The liquidGlass singleton is the primary entry point for applying glass/vibrancy effects to Electron windows. It handles platform checks (macOS only) and native addon loading internally. If the environment is not macOS or the native addon fails to load, the functionality is gracefully disabled.

To apply an effect, use addView by passing the native window handle obtained from BrowserWindow.getNativeWindowHandle().

import liquidGlass from 'electron-liquid-glass';

// Assuming you have an Electron BrowserWindow instance named 'mainWindow'
const handle = mainWindow.getNativeWindowHandle();
const viewId = liquidGlass.addView(handle, {
  cornerRadius: 10,
  tintColor: '#ffffff',
  opaque: false
});

if (viewId === -1) {
  console.log('Liquid glass is not supported on this platform/version.');
}

Wraps an Electron window with a glass/vibrancy view. It will gracefully fall back to legacy macOS blur if liquid glass is not supported by the OS.

Parameters:

• handle: A Buffer representing the native window handle (use BrowserWindow.getNativeWindowHandle()).
• options: An optional GlassOptions object.

Returns:

• A number representing the view ID (used for future updates/removal).
• -1 if the effect is not supported on the current platform.

const viewId = liquidGlass.addView(handle, { cornerRadius: 8 });

Use isGlassSupported() to determine if the current environment can use the liquid glass effect. The library requires macOS with a product version of 26 or higher. If not supported, addView will return -1.

if (liquidGlass.isGlassSupported()) {
  // Proceed with adding glass views
}

The following methods are marked as unstable and are used to modify the state of an existing glass view using its viewId (returned by addView).

• unstable_setVariant(id: number, variant: GlassMaterialVariant): Sets the material variant for the view.
• unstable_setScrim(id: number, scrim: number): Sets the scrim state.
• unstable_setSubdued(id: number, subdued: number): Sets the subdued state.

// Example of using an unstable method
liquidGlass.unstable_setVariant(viewId, liquidGlass.GlassMaterialVariant.SOME_VARIANT);

The GlassOptions interface defines the visual properties of the glass effect applied to a window handle.

Note: All options are optional.

export interface GlassOptions {
  cornerRadius?: number;
  tintColor?: string;
  opaque?: boolean;
}