Window Customization

    A frameless window is a window that has no chrome. Not to be confused with the Google Chrome browser, window chrome refers to the parts of the window (e.g. toolbars, controls) that are not a part of the web page.

    To create a frameless window, you need to set frame to false in the BrowserWindow constructor.

    ```javascript title=’main.js’ const { BrowserWindow } = require(‘electron’) const win = new BrowserWindow({ frame: false })

    On macOS, applying the hidden title bar style will still expose the standard window controls (“traffic lights”) in the top left.

    Customize the look of your traffic lights macOS

    The customButtonsOnHover title bar style will hide 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.

    1. const { BrowserWindow } = require('electron')
    2. const win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover' })

    Customize the traffic light position macOS

    Applying hiddenInset title bar style will shift the vertical inset of the traffic lights by a fixed amount.

    ```javascript title=’main.js’ const { BrowserWindow } = require(‘electron’) const win = new BrowserWindow({ titleBarStyle: ‘hiddenInset’ })

    Show and hide the traffic lights programmatically macOS

    You can also show and hide the traffic lights programmatically from the main process. The win.setWindowButtonVisibility forces traffic lights to be show or hidden depending on the value of its boolean parameter.

    ```javascript title=’main.js’ const { BrowserWindow } = require(‘electron’) const win = new BrowserWindow() // hides the traffic lights win.setWindowButtonVisibility(false)

    2. > Note: Given the number of APIs available, there are many ways of achieving this. For instance,
    3. > combining `frame: false` with `win.setWindowButtonVisibility(true)` will yield the same
    4. > layout outcome as setting `titleBarStyle: 'hidden'`.
    6. ## Window Controls Overlay _macOS_ _Windows_
    8. The [Window Controls Overlay API] is a web standard that gives web apps the ability to
    9. customize their title bar region when installed on desktop. Electron exposes this API
    10. through the `BrowserWindow` constructor option `titleBarOverlay`.
    12. This option only works whenever a custom `titlebarStyle` is applied on macOS or Windows.
    13. When `titleBarOverlay` is enabled, the window controls become exposed in their default
    14. position, and DOM elements cannot use the area underneath this region.
    16. The `titleBarOverlay` option accepts two different value formats.
    18. system colors:
    20. ```javascript title='main.js'
    21. // on macOS or Windows
    22. const { BrowserWindow } = require('electron')
    23. const win = new BrowserWindow({
    24.   titleBarStyle: 'hidden',
    25.   titleBarOverlay: true
    26. })

    On Windows, you can also specify the color of the overlay and its symbols by setting titleBarOverlay to an object with the color and symbolColor properties. If an option is not specified, the color will default to its system color for the window control buttons:

    • You cannot click through the transparent area. See #1335 for details.
    • Transparent windows are not resizable. Setting resizable to true may make a transparent window stop working on some platforms.
    • The CSS filter only applies to the window’s web contents, so there is no way to apply blur effect to the content below the window (i.e. other applications open on the user’s system).
    • The window will not be transparent when DevTools is opened.
    • On Windows:
      • Transparent windows will not work when DWM is disabled.
      • Transparent windows can not be maximized using the Windows system menu or by double clicking the title bar. The reasoning behind this can be seen on PR #28207.
    • On macOS:
      • The native window shadow will not be shown on a transparent window.

    Create click-through windows

    To create a click-through window, i.e. making the window ignore all mouse events, you can call the win.setIgnoreMouseEvents(ignore) API:

    ```javascript title=’main.js’ const { BrowserWindow } = require(‘electron’) const win = new BrowserWindow() win.setIgnoreMouseEvents(true)

    2. ### Forward mouse events _macOS_ _Windows_
    4. Ignoring mouse messages makes the web contents oblivious to mouse movement,
    5. meaning that mouse movement events will not be emitted. On Windows and macOS, an
    6. optional parameter can be used to forward mouse move messages to the web page,
    7. allowing events such as `mouseleave` to be emitted:
    9. ```javascript title='main.js'
    10. const path = require('path')
    12. const win = new BrowserWindow({
    13.   webPreferences: {
    14.     preload: path.join(__dirname, 'preload.js')
    15.   }
    16. })
    18. ipcMain.on('set-ignore-mouse-events', (event, ...args) => {
    19.   const win = BrowserWindow.fromWebContents(event.sender)
    20.   win.setIgnoreMouseEvents(...args)
    21. })

    ```javascript title=’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) }) })

    And note that if you have made the whole window draggable, you must also mark buttons as non-draggable, otherwise it would be impossible for users to click on them:

    ```css title=’styles.css’ button { -webkit-app-region: no-drag; }

    2. If you're only setting a custom titlebar as draggable, you also need to make all
    3. buttons in titlebar non-draggable.
    5. ### Tip: disable text selection
    7. When creating a draggable region, the dragging behavior may conflict with text selection.
    8. For example, when you drag the titlebar, you may accidentally select its text contents.
    9. To prevent this, you need to disable text selection within a draggable area like this:
    11. ```css
    12. .titlebar {
    13.   -webkit-user-select: none;
    15. }