Example setWindowButtonVisibility usage
const { BrowserWindow } = require('electron') const win = new BrowserWindow() // hides the traffic lights win.setWindowButtonVisibility(false)
Electron · Tutorial · all subjects
window-customization
47 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
frame false with setWindowButtonVisibility true equivalent to titleBarStyle hidden
Combining frame: false with win.setWindowButtonVisibility(true) yields the same layout outcome as setting titleBarStyle: 'hidden'.
Remove default title bar with titleBarStyle hidden
To remove the default title bar from a BrowserWindow, set the titleBarStyle parameter in the BaseWindowConstructorOptions to 'hidden' in the BrowserWindow constructor.
macOS traffic lights behavior with titleBarStyle hidden
On macOS, setting titleBarStyle to 'hidden' removes the title bar while keeping the window's traffic light controls available in the upper left hand corner.
Windows and Linux require titleBarOverlay for window controls
On Windows and Linux, when titleBarStyle is set to 'hidden', you must add window controls back into the BrowserWindow by setting the titleBarOverlay parameter in the BrowserWindow constructor.
Make custom title bar draggable with app-region CSS
To make a custom title bar draggable, add the CSS style 'app-region: drag' to the custom title bar element. This tells Electron which regions are draggable so the window can be repositioned.
Safe title bar area with CSS environment variables
To prevent custom title bar content from overlapping with native window controls, use the CSS variables 'env(titlebar-area-x, 0px)' and 'env(titlebar-area-width, 100%)' to create a safe area that accounts for button positioning on either side of the frame.
customButtonsOnHover title bar style for macOS
The 'customButtonsOnHover' title bar style hides the traffic lights until you hover over them. This is useful if you want to create custom traffic lights in your HTML but still use the native UI to control the window.
hiddenInset title bar style shifts traffic light position macOS
The 'hiddenInset' title bar style shifts the vertical inset of the traffic lights by a fixed amount on macOS, allowing you to modify the position of the traffic light window controls.
trafficLightPosition option for macOS traffic light positioning
For granular control over the positioning of traffic lights on macOS, pass a set of coordinates to the trafficLightPosition option in the BrowserWindow constructor. It accepts an object with x and y properties: { x: 10, y: 10 }.
setWindowButtonVisibility programmatically controls traffic lights macOS
You can show and hide the traffic lights programmatically from the main process using the win.setWindowButtonVisibility() method. It takes a boolean parameter to force traffic lights to be shown or hidden.
titleBarOverlay requires non-default titleBarStyle
The titleBarOverlay option requires the titleBarStyle parameter in the BrowserWindow constructor to have a value other than 'default'.
titleBarOverlay object configuration for height and colors
The titleBarOverlay option can be set to an object to customize the height, color, and symbol colors of window controls. The height property must be an integer. The color and symbolColor properties accept rgba(), hsla(), and #RRGGBBAA color formats and support transparency. If not specified, colors default to system colors and height defaults to standard system height.
titleBarOverlay color and dimension access from renderer
Once titleBarOverlay is enabled from the main process, the overlay's color and dimension values can be accessed from a renderer using readonly JavaScript APIs and CSS Environment Variables.
Example titleBarOverlay configuration
const { BrowserWindow } = require('electron') const win = new BrowserWindow({ titleBarStyle: 'hidden', titleBarOverlay: { color: '#2f3241', symbolColor: '#74b1be', height: 60 } })
Example customButtonsOnHover titleBarStyle
const { BrowserWindow } = require('electron') const win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover' })
Example trafficLightPosition configuration
const { BrowserWindow } = require('electron') const win = new BrowserWindow({ titleBarStyle: 'hidden', trafficLightPosition: { x: 10, y: 10 } })
Transparent window DevTools limitation
The window will not be transparent when DevTools is opened.
Transparent windows cannot receive clicks through transparent areas
You cannot click through the transparent area of a transparent window. This is a limitation documented in Electron issue #1335.
Frameless window creation
To create a frameless window that removes all OS chrome and window controls, set the `frame` parameter to `false` in the `BrowserWindow` constructor's `BaseWindowConstructorOptions`.
Frameless windows on Wayland Linux
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 windows resize limitation
Transparent windows are not resizable. Setting `resizable` to `true` may make a transparent window stop working on some platforms.
CSS blur filter does not affect content below transparent window
The CSS `blur()` filter only applies to the window's web contents. There is no way to apply a blur effect to the content below the window, such as other applications open on the user's system.
Transparent window creation
To create a fully transparent window, set the `transparent` parameter to `true` in the `BrowserWindow` constructor's `BaseWindowConstructorOptions`.
Transparent windows on Windows cannot be maximized
On Windows, transparent windows cannot be maximized using the Windows system menu or by double-clicking the title bar. This limitation is documented in PR #28207.
Native window shadow not shown on transparent windows on macOS
On macOS, the native window shadow will not be shown on a transparent window.
nativeTheme.themeSource property controls manual dark mode
The themeSource property of the nativeTheme module allows manual switching between light and dark modes. Setting this property propagates the value to the Renderer process, and any CSS rules related to prefers-color-scheme are updated accordingly.
prefers-color-scheme CSS media query for auto-syncing app theme
If your app has its own dark mode, you can toggle it automatically in sync with the system's dark mode setting by using the prefers-color-scheme CSS media query. This keeps the app interface synchronized with the operating system's theme without manual intervention.
Native interfaces auto-theme from OS by default
Native interfaces include the file picker, window border, dialogs, context menus, and other UI elements that come from the operating system rather than the app. By default, Electron automatically applies the system's theme to these native interfaces.
macOS 10.14+ dark mode support via nativeTheme API
macOS 10.14 Mojave introduced system-wide dark mode. Electron apps can follow the system-wide dark mode setting using the nativeTheme API.
macOS 10.15 Catalina automatic dark mode requires configuration
In macOS 10.15 Catalina, Apple introduced an 'automatic' dark mode option. For nativeTheme.shouldUseDarkColors and Tray APIs to work correctly in this mode on Catalina, you need to use Electron >=7.0.0, or set NSRequiresAquaSystemAppearance to false in the Info.plist file for older versions.
macOS NSRequiresAquaSystemAppearance Info.plist key
To opt-out of dark mode theming on macOS while using Electron > 8.0.0, set the NSRequiresAquaSystemAppearance key in the Info.plist file to true. Note that Electron 8.0.0 and above will not let you opt-out of this theming due to use of the macOS 10.14 SDK.
Dark mode IPC example with preload bridge
The preload.js script exposes a darkMode API to the renderer process using contextBridge.exposeInMainWorld with two methods: toggle() and system(). These methods use ipcRenderer.invoke to send 'dark-mode:toggle' and 'dark-mode:system' messages to the main process securely.
Dark mode toggle handler in main process
ipcMain.handle('dark-mode:toggle', () => { if (nativeTheme.shouldUseDarkColors) { nativeTheme.themeSource = 'light' } else { nativeTheme.themeSource = 'dark' } return nativeTheme.shouldUseDarkColors }) - This handler checks the current shouldUseDarkColors boolean, toggles themeSource between 'light' and 'dark', and returns the updated shouldUseDarkColors value.
Dark mode system reset handler in main process
ipcMain.handle('dark-mode:system', () => { nativeTheme.themeSource = 'system' }) - This handler resets the theme source to follow the system setting.
prefers-color-scheme media queries example
@media (prefers-color-scheme: dark) { body { background: #333; color: white; } } @media (prefers-color-scheme: light) { body { background: #ddd; color: black; } } - Use these CSS media queries to conditionally apply styles based on the system's color scheme preference.
Offscreen window is always frameless
An offscreen window is always created as a Frameless Window.
setRepresentedFilename API for macOS title bar
On macOS, you can set a represented file for a BrowserWindow using the setRepresentedFilename() API. The represented file's icon will be shown in the title bar. When users Command-Click or Control-Click on the title bar, a popup with the path to the file will be shown.
setDocumentEdited API for macOS window state
You can set the edited state for a macOS BrowserWindow using the setDocumentEdited() API. This allows the file icon in the title bar to indicate whether the document in the window has been modified.
Represented file example code
The following code sets a represented filename and document edited state for a macOS window: const { app, BrowserWindow } = require('electron/main') const os = require('node:os') function createWindow () { const win = new BrowserWindow({ width: 800, height: 600 }) win.setRepresentedFilename(os.homedir()) win.setDocumentEdited(true) win.loadFile('index.html') } app.whenReady().then(() => { createWindow() app.on('activate', () => { if (BrowserWindow.getAllWindows().length === 0) { createWindow() } }) }) app.on('window-all-closed', () => { if (process.platform !== 'darwin') { app.quit() } })
Tray icon platform locations
On macOS, the tray icon appears in the top right corner in the menu bar extras area. On Windows, it appears in the notification area at the end of the taskbar. On Linux, the location differs based on the desktop environment.
Tray icon creation requires NativeImage or file path
The Tray class constructor requires a single instance of NativeImage or a path to a compatible icon file. File formats vary per operating system.
Tray object must be kept in global reference to avoid garbage collection
The Tray object should be saved in a global reference to prevent garbage collection.
Example of creating Tray icon with context menu
const { nativeImage } = require('electron/common') const { app, Tray, Menu } = require('electron/main') let tray const icon = nativeImage.createFromDataURL('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAACTSURBVHgBpZKBCYAgEEV/TeAIjuIIbdQIuUGt0CS1gW1iZ2jIVaTnhw+Cvs8/OYDJA4Y8kR3ZR2/kmazxJbpUEfQ/Dm/UG7wVwHkjlQdMFfDdJMFaACebnjJGyDWgcnZu1/lrCrl6NCoEHJBrDwEr5NrT6ko/UV8xdLAC2N49mlc5CylpYh8wCwqrvbBGLoKGvz8Bfq0QPWEUo/EAAAAASUVORK5CYII=') app.whenReady().then(() => { tray = new Tray(icon) const contextMenu = Menu.buildFromTemplate([ { role: 'quit' } ]) tray.setContextMenu(contextMenu) }) This example creates a 16x16 red circle icon and attaches a quit menu item to the tray context menu.
BrowserWindow module is foundation for Electron windows
The BrowserWindow module is the foundation of an Electron application and exposes many APIs for customizing the look and behavior of application windows.
BrowserWindow vs BaseWindow difference
BrowserWindow is a subclass of BaseWindow. Both modules allow you to create and manage application windows in Electron. The main difference is that BrowserWindow supports a single, full size web view while BaseWindow supports composing many web views.
BaseWindow can be used interchangeably with BrowserWindow
BaseWindow can be used interchangeably with BrowserWindow in window customization examples.