Create offscreen window with webPreferences.offscreen
To create an offscreen window, pass webPreferences.offscreen: true when creating a BrowserWindow.
app lifecycle & windows
21 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Offscreen window is frameless
An offscreen window is always created as a Frameless Window.
Avoid custom context menus on draggable areas
On some platforms, draggable areas are treated as non-client frames, causing system menus to pop up on right-click. To ensure context menus behave correctly across all platforms, avoid using custom context menus on draggable areas.
app-region CSS property for draggable windows
The `app-region` CSS property defines draggable areas in Electron windows when the default OS title bar has been removed. Setting `app-region: drag` marks a rectangular area as draggable, and setting `app-region: no-drag` excludes a rectangular area from being draggable.
Draggable regions ignore pointer events
Draggable areas (marked with `app-region: drag`) ignore all pointer events. Button elements and other interactive elements that overlap a draggable region will not emit mouse clicks or mouse enter/exit events within that overlapping area. Use `app-region: no-drag` to re-enable pointer events for specific elements.
Making whole window draggable with app-region
To make the whole window draggable, add `app-region: drag` to the `body` element style. When doing this, you must also mark buttons as non-draggable with `app-region: no-drag`, otherwise users will be unable to click on them.
Disable text selection in draggable regions
To prevent accidental text selection when dragging in a draggable region, use the CSS property `user-select: none` on the draggable element.
win.setIgnoreMouseEvents() creates click-through windows
The `win.setIgnoreMouseEvents(ignore)` API makes a window ignore all mouse events, creating a click-through window. When called with `ignore` set to true, the window becomes transparent to mouse clicks.
win.setIgnoreMouseEvents() basic example
const { BrowserWindow } = require('electron') const win = new BrowserWindow() win.setIgnoreMouseEvents(true)
Forward mouse move events in setIgnoreMouseEvents on Windows and macOS
On Windows and macOS, `win.setIgnoreMouseEvents(ignore, options)` accepts an optional `options` parameter. With `{ forward: true }`, mouse move messages are forwarded to the web page, allowing events such as `mouseleave` to be emitted even when mouse events are being ignored.
Forward mouse events example with ipcMain and ipcRenderer
// main.js const { BrowserWindow, ipcMain } = require('electron') const path = require('node:path') const win = new BrowserWindow({ webPreferences: { preload: path.join(__dirname, 'preload.js') } }) ipcMain.on('set-ignore-mouse-events', (event, ignore, options) => { const win = BrowserWindow.fromWebContents(event.sender) win.setIgnoreMouseEvents(ignore, options) }) // preload.js window.addEventListener('DOMContentLoaded', () => { const el = document.getElementById('clickThroughElement') el.addEventListener('mouseenter', () => { ipcRenderer.send('set-ignore-mouse-events', true, { forward: true }) }) el.addEventListener('mouseleave', () => { ipcRenderer.send('set-ignore-mouse-events', false) }) })
Click-through region implementation pattern
To make a specific region click-through while keeping the rest of the window normal, use ipcRenderer to send `setIgnoreMouseEvents(true, { forward: true })` on mouseenter and `setIgnoreMouseEvents(false)` on mouseleave for that region.
Transparent windows on Windows: cannot maximize via system menu or double-click
On Windows, transparent windows cannot be maximized using the Windows system menu or by double-clicking the title bar.
Transparent windows on macOS: no native window shadow
On macOS, the native window shadow will not be shown on a transparent window.
Transparent windows not transparent when DevTools is opened
The window will not be transparent when DevTools is opened.
Frameless windows on Wayland: GTK drop shadows and hasShadow option
On Wayland (Linux), frameless windows have GTK drop shadows and extended resize boundaries by default. To create a fully frameless window with no decorations on Wayland, set hasShadow: false in the window constructor options.
Transparent window creation with transparent parameter
To create a fully transparent window, set the transparent parameter in BaseWindowConstructorOptions to true in the BrowserWindow constructor.
Transparent windows limitation: cannot click through transparent area
Transparent windows cannot be clicked through in the transparent area.
Transparent windows limitation: not resizable
Transparent windows are not resizable. Setting resizable to true may make a transparent window stop working on some platforms.
CSS blur filter limitation on transparent windows
The CSS blur() filter only applies to the window's web contents. There is no way to apply blur effect to the content below the window (other applications open on the user's system).
Frameless window creation with frame parameter
To create a frameless window that removes all OS chrome including window controls, set the frame parameter in BaseWindowConstructorOptions to false in the BrowserWindow constructor.