README.md

💫 @pyke/vibe 💫

native windows acrylic effects for electron

---

vibe is a library for acrylic/vibrancy effects for Electron on Windows 10/11. Any Electron version compatible with N-API v6 (Electron v11+) is supported.

---

Maintenance note

Native support for Windows background materials recently landed in Electron: electron/electron#38163

vibe will continue to be maintained until Electron v25+ becomes mainstream.

---

Requirements

A recent version of Rust (>=1.56.1) is required. You can install it via rustup.

If you don't plan on doing Rust development, you may choose to install the minimal profile in rustup to install a lighter Rust toolchain.

For end users, the Acrylic effect is supported in Windows 10 builds later than build 17763, and the Mica effect is supported in Windows 11 only. vibe uses an undocumented API for enabling Mica on early builds of Windows 11 (specifically pre-22H2, build <22523) that is not heavily tested and may not work at all.

Usage

Note: If you'd like to use vibe with Discord on Windows, you'll need to install an additional Rust target: rustup target add i686-pc-windows-msvc, then build vibe with npm run build:windows-i686. You can then use the resulting index.node file like you'd use @pyke/vibe.

There are 3 important points you must keep in mind when using vibe:

• vibe must do some trickery on the Electron app object before Electron loads in order for effects to work, so don't forget to run vibe.setup(app) before app.whenReady().
• Keep the default frame. Windows gets fussy about frames when you attempt to use acrylic effects. titleBarStyle must always be set to default and frame must always be set to true. While there is a way to have titlebar-less framed Mica windows, it does not work with Electron, and would unfortunately require changes in Electron's internals.
• Both html and body need to be transparent in CSS. It's a common mistake to only make either html or body have background: transparent, but both of them need to be transparent. Additionally, you must set the Electron window's backgroundColor to #00000000 to trick Electron into making a framed transparent window. Do not set transparent to true, as this will disable the frame and effects will break.

const { app, BrowserWindow, nativeTheme } = require('electron');
const vibe = require('@pyke/vibe');

// Very important - let vibe perform its magic before the app is ready
vibe.setup(app);

app.whenReady().then(() => {
    const mainWindow = new BrowserWindow({
        ...,

        // This part is very important!
        backgroundColor: '#00000000',

        // Recommendation: Wait to show the window to avoid an ugly flash of non-acrylic-ized content.
        show: false,
        // Recommendation: Hide the menu bar, as the colour of the bar will be solid and will look janky.
        autoHideMenuBar: true
    });

    // Apply effects! 💫
    // This should be run before the window is ready to be shown.
    vibe.applyEffect(mainWindow, 'acrylic');

    // To disable effects, run `clearEffects`.
    // The background colour of the window will be black, so you should reset the window's background colour here and/or send a message to the renderer to update the CSS.
    vibe.clearEffects(mainWindow);
    mainWindow.setBackgroundColor('#ffffff');
});

The acrylic effect for Windows 10 and below can also have a 'tint' applied to it:

vibe.applyEffect(mainWindow, 'acrylic', '#AA80FF40');

NOTE: The Windows 11 22H2 'Fluent' Acrylic & Mica effects cannot be tinted and will simply follow the window/system theme (see below). You can use vibe.platform.isWin11_22H2() to detect if the system is Windows 11 22H2 or greater and style your app appropriately.

const supportsFluentAcrylic = vibe.platform.isWin11_22H2(); // Win 11 before 22H2 does not support Fluent Acrylic
const supportsMica = vibe.platform.isWin11();
const supportsTintableAcrylic = !vibe.platform.isWin11();

Additionally, you can use Electron's nativeTheme module to force the theme of the acrylic effects:

const { nativeTheme } = require('electron');
nativeTheme.themeSource = 'dark';

or, for older versions of Electron:

vibe.forceTheme(mainWindow, 'dark');
vibe.forceTheme(mainWindow, 'light');

Need help? Visit the #📕｜vibe channel in the pyke Discord server:

Known issues

• Enabling the "Show accent color on title bars and windows borders" setting in Personalization > Colors on Windows styles the titlebar as a solid colour when using the Mica & Acrylic effects.
  • Workaround: No workaround, but disabling the setting fixes it.
• blurbehind does not work on Windows 11 and later Windows 10 builds.
  • Workaround: Use acrylic or unified-acrylic on these platforms instead.
• unified-acrylic lags when moving the window on Windows 11 and later Windows 10 builds.
  • Workaround: None, this is a long standing issue with Windows that will likely never be fixed. Use the fluent acrylic effect instead;

Thanks to:

• Tauri's window-vibrancy package, which vibe borrows some code from.
• @alexmercerind for discovering the DwmExtendFrameIntoClientArea hack
• @sylveon for finding a workaround to transparent: true
• @GregVido for discovering the enable-transparent-visuals hack
• Twitter for providing the vibe 'icon' used in the demo 💫