BrowserWindow
Create and control browser windows.
Process: Main
This module cannot be used until the ready
event of the app
module is emitted.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')
win.loadFile('index.html')
Window customization
The BrowserWindow
class exposes various ways to modify the look and behavior of
your app's windows. For more details, see the Window Customization
tutorial.
Showing the window gracefully
When loading a page in the window directly, users may see the page load incrementally,
which is not a good experience for a native app. To make the window display
without a visual flash, there are two solutions for different situations.
Using the ready-to-show
event
While loading the page, the ready-to-show
event will be emitted when the renderer
process has rendered the page for the first time if the window has not been shown yet. Showing
the window after this event will have no visual flash:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ show: false })
win.once('ready-to-show', () => {
win.show()
})
This event is usually emitted after the did-finish-load
event, but for
pages with many remote resources, it may be emitted before the did-finish-load
event.
Please note that using this event implies that the renderer will be considered "visible" and
paint even though show
is false. This event will never fire if you use paintWhenInitiallyHidden: false
Setting the backgroundColor
property
For a complex app, the ready-to-show
event could be emitted too late, making
the app feel slow. In this case, it is recommended to show the window
immediately, and use a backgroundColor
close to your app's background:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ backgroundColor: '#2e2c29' })
win.loadURL('https://github.com')
Note that even for apps that use ready-to-show
event, it is still recommended
to set backgroundColor
to make the app feel more native.
Some examples of valid backgroundColor
values include:
const win = new BrowserWindow()
win.setBackgroundColor('hsl(230, 100%, 50%)')
win.setBackgroundColor('rgb(255, 145, 145)')
win.setBackgroundColor('#ff00a3')
win.setBackgroundColor('blueviolet')
For more information about these color types see valid options in win.setBackgroundColor.
Parent and child windows
By using parent
option, you can create child windows:
const { BrowserWindow } = require('electron')
const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top })
child.show()
top.show()
The child
window will always show on top of the top
window.
Modal windows
A modal window is a child window that disables parent window. To create a modal
window, you have to set both the parent
and modal
options:
const { BrowserWindow } = require('electron')
const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top, modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
child.show()
})
Page visibility
The Page Visibility API works as follows:
- On all platforms, the visibility state tracks whether the window is
hidden/minimized or not.
- Additionally, on macOS, the visibility state also tracks the window
occlusion state. If the window is occluded (i.e. fully covered) by another
window, the visibility state will be
hidden
. On other platforms, the
visibility state will be hidden
only when the window is minimized or
explicitly hidden with win.hide()
.
- If a
BrowserWindow
is created with show: false
, the initial visibility
state will be visible
despite the window actually being hidden.
- If
backgroundThrottling
is disabled, the visibility state will remain
visible
even if the window is minimized, occluded, or hidden.
It is recommended that you pause expensive operations when the visibility
state is hidden
in order to minimize power consumption.
- On macOS modal windows will be displayed as sheets attached to the parent window.
- On macOS the child windows will keep the relative position to parent window
when parent window moves, while on Windows and Linux child windows will not
move.
- On Linux the type of modal windows will be changed to
dialog
.
- On Linux many desktop environments do not support hiding a modal window.
Class: BrowserWindow extends BaseWindow
Create and control browser windows.
Process: Main
BrowserWindow
is an EventEmitter.
It creates a new BrowserWindow
with native properties as set by the options
.
new BrowserWindow([options])
options
BrowserWindowConstructorOptions (optional)
webPreferences
WebPreferences (optional) - Settings of web page's features.
devTools
boolean (optional) - Whether to enable DevTools. If it is set to false
, can not use BrowserWindow.webContents.openDevTools()
to open DevTools. Default is true
.
nodeIntegration
boolean (optional) - Whether node integration is enabled.
Default is false
.
nodeIntegrationInWorker
boolean (optional) - Whether node integration is
enabled in web workers. Default is false
. More about this can be found
in Multithreading.
nodeIntegrationInSubFrames
boolean (optional) - Experimental option for
enabling Node.js support in sub-frames such as iframes and child windows. All your preloads will load for
every iframe, you can use process.isMainFrame
to determine if you are
in the main frame or not.
preload
string (optional) - Specifies a script that will be loaded before other
scripts run in the page. This script will always have access to node APIs
no matter whether node integration is turned on or off. The value should
be the absolute file path to the script.
When node integration is turned off, the preload script can reintroduce
Node global symbols back to the global scope. See example
here.
sandbox
boolean (optional) - If set, this will sandbox the renderer
associated with the window, making it compatible with the Chromium
OS-level sandbox and disabling the Node.js engine. This is not the same as
the nodeIntegration
option and the APIs available to the preload script
are more limited. Read more about the option here.
session
Session (optional) - Sets the session used by the
page. Instead of passing the Session object directly, you can also choose to
use the partition
option instead, which accepts a partition string. When
both session
and partition
are provided, session
will be preferred.
Default is the default session.
partition
string (optional) - Sets the session used by the page according to the
session's partition string. If partition
starts with persist:
, the page
will use a persistent session available to all pages in the app with the
same partition
. If there is no persist:
prefix, the page will use an
in-memory session. By assigning the same partition
, multiple pages can share
the same session. Default is the default session.
zoomFactor
number (optional) - The default zoom factor of the page, 3.0
represents
300%
. Default is 1.0
.
javascript
boolean (optional) - Enables JavaScript support. Default is true
.
webSecurity
boolean (optional) - When false
, it will disable the
same-origin policy (usually using testing websites by people), and set
allowRunningInsecureContent
to true
if this options has not been set
by user. Default is true
.
allowRunningInsecureContent
boolean (optional) - Allow an https page to run
JavaScript, CSS or plugins from http URLs. Default is false
.
images
boolean (optional) - Enables image support. Default is true
.
imageAnimationPolicy
string (optional) - Specifies how to run image animations (E.g. GIFs). Can be animate
, animateOnce
or noAnimation
. Default is animate
.
textAreasAreResizable
boolean (optional) - Make TextArea elements resizable. Default
is true
.
webgl
boolean (optional) - Enables WebGL support. Default is true
.
plugins
boolean (optional) - Whether plugins should be enabled. Default is false
.
experimentalFeatures
boolean (optional) - Enables Chromium's experimental features.
Default is false
.
scrollBounce
boolean (optional) macOS - Enables scroll bounce
(rubber banding) effect on macOS. Default is false
.
enableBlinkFeatures
string (optional) - A list of feature strings separated by ,
, like
CSSVariables,KeyboardEventKey
to enable. The full list of supported feature
strings can be found in the RuntimeEnabledFeatures.json5
file.
disableBlinkFeatures
string (optional) - A list of feature strings separated by ,
,
like CSSVariables,KeyboardEventKey
to disable. The full list of supported
feature strings can be found in the
RuntimeEnabledFeatures.json5 file.
defaultFontFamily
Object (optional) - Sets the default font for the font-family.
standard
string (optional) - Defaults to Times New Roman
.
serif
string (optional) - Defaults to Times New Roman
.
sansSerif
string (optional) - Defaults to Arial
.
monospace
string (optional) - Defaults to Courier New
.
cursive
string (optional) - Defaults to Script
.
fantasy
string (optional) - Defaults to Impact
.
math
string (optional) - Defaults to Latin Modern Math
.
defaultFontSize
Integer (optional) - Defaults to 16
.
defaultMonospaceFontSize
Integer (optional) - Defaults to 13
.
minimumFontSize
Integer (optional) - Defaults to 0
.
defaultEncoding
string (optional) - Defaults to ISO-8859-1
.
backgroundThrottling
boolean (optional) - Whether to throttle animations and timers
when the page becomes background. This also affects the
Page Visibility API. When at least one
webContents displayed in a single
browserWindow has disabled backgroundThrottling
then
frames will be drawn and swapped for the whole window and other
webContents displayed by it. Defaults to true
.
offscreen
boolean (optional) - Whether to enable offscreen rendering for the browser
window. Defaults to false
. See the
offscreen rendering tutorial for
more details.
contextIsolation
boolean (optional) - Whether to run Electron APIs and
the specified preload
script in a separate JavaScript context. Defaults
to true
. The context that the preload
script runs in will only have
access to its own dedicated document
and window
globals, as well as
its own set of JavaScript builtins (Array
, Object
, JSON
, etc.),
which are all invisible to the loaded content. The Electron API will only
be available in the preload
script and not the loaded page. This option
should be used when loading potentially untrusted remote content to ensure
the loaded content cannot tamper with the preload
script and any
Electron APIs being used. This option uses the same technique used by
Chrome Content Scripts. You can access this
context in the dev tools by selecting the 'Electron Isolated Context'
entry in the combo box at the top of the Console tab.
webviewTag
boolean (optional) - Whether to enable the <webview>
tag.
Defaults to false
. Note: The
preload
script configured for the <webview>
will have node integration
enabled when it is executed so you should ensure remote/untrusted content
is not able to create a <webview>
tag with a possibly malicious preload
script. You can use the will-attach-webview
event on webContents
to strip away the preload
script and to validate or alter the
<webview>
's initial settings.
additionalArguments
string[] (optional) - A list of strings that will be appended
to process.argv
in the renderer process of this app. Useful for passing small
bits of data down to renderer process preload scripts.
safeDialogs
boolean (optional) - Whether to enable browser style
consecutive dialog protection. Default is false
.
safeDialogsMessage
string (optional) - The message to display when
consecutive dialog protection is triggered. If not defined the default
message would be used, note that currently the default message is in
English and not localized.
disableDialogs
boolean (optional) - Whether to disable dialogs
completely. Overrides safeDialogs
. Default is false
.
navigateOnDragDrop
boolean (optional) - Whether dragging and dropping a
file or link onto the page causes a navigation. Default is false
.
autoplayPolicy
string (optional) - Autoplay policy to apply to
content in the window, can be no-user-gesture-required
,
user-gesture-required
, document-user-activation-required
. Defaults to
no-user-gesture-required
.
disableHtmlFullscreenWindowResize
boolean (optional) - Whether to
prevent the window from resizing when entering HTML Fullscreen. Default
is false
.
accessibleTitle
string (optional) - An alternative title string provided only
to accessibility tools such as screen readers. This string is not directly
visible to users.
spellcheck
boolean (optional) - Whether to enable the builtin spellchecker.
Default is true
.
enableWebSQL
boolean (optional) - Whether to enable the WebSQL api.
Default is true
.
v8CacheOptions
string (optional) - Enforces the v8 code caching policy
used by blink. Accepted values are
none
- Disables code caching
code
- Heuristic based code caching
bypassHeatCheck
- Bypass code caching heuristics but with lazy compilation
bypassHeatCheckAndEagerCompile
- Same as above except compilation is eager.
Default policy is code
.
enablePreferredSizeMode
boolean (optional) - Whether to enable
preferred size mode. The preferred size is the minimum size needed to
contain the layout of the document—without requiring scrolling. Enabling
this will cause the preferred-size-changed
event to be emitted on the
WebContents
when the preferred size changes. Default is false
.
transparent
boolean (optional) - Whether to enable background transparency for the guest page. Default is true
. Note: The guest page's text and background colors are derived from the color scheme of its root element. When transparency is enabled, the text color will still change accordingly but the background will remain transparent.
paintWhenInitiallyHidden
boolean (optional) - Whether the renderer should be active when show
is false
and it has just been created. In order for document.visibilityState
to work correctly on first load with show: false
you should set this to false
. Setting this to false
will cause the ready-to-show
event to not fire. Default is true
.
titleBarOverlay
Object | Boolean (optional) - When using a frameless window in conjunction with win.setWindowButtonVisibility(true)
on macOS or using a titleBarStyle
so that the standard window controls ("traffic lights" on macOS) are visible, this property enables the Window Controls Overlay JavaScript APIs and CSS Environment Variables. Specifying true
will result in an overlay with default system colors. Default is false
.
color
String (optional) Windows - The CSS color of the Window Controls Overlay when enabled. Default is the system color.
symbolColor
String (optional) Windows - The CSS color of the symbols on the Window Controls Overlay when enabled. Default is the system color.
height
Integer (optional) macOS Windows - The height of the title bar and Window Controls Overlay in pixels. Default is system height.
Instance Events
Objects created with new BrowserWindow
emit the following events:
Note: Some events are only available on specific operating systems and are
labeled as such.
Event: 'page-title-updated'
Returns:
event
Event
title
string
explicitSet
boolean
Emitted when the document changed its title, calling event.preventDefault()
will prevent the native window's title from changing.
explicitSet
is false when title is synthesized from file URL.
Event: 'close'
Returns:
Emitted when the window is going to be closed. It's emitted before the
beforeunload
and unload
event of the DOM. Calling event.preventDefault()
will cancel the close.
Usually you would want to use the beforeunload
handler to decide whether the
window should be closed, which will also be called when the window is
reloaded. In Electron, returning any value other than undefined
would cancel the
close. For example:
window.onbeforeunload = (e) => {
console.log('I do not want to be closed')
e.returnValue = false
}
Note: There is a subtle difference between the behaviors of window.onbeforeunload = handler
and window.addEventListener('beforeunload', handler)
. It is recommended to always set the event.returnValue
explicitly, instead of only returning a value, as the former works more consistently within Electron.
Event: 'closed'
Emitted when the window is closed. After you have received this event you should
remove the reference to the window and avoid using it any more.
Event: 'session-end' Windows
Emitted when window session is going to end due to force shutdown or machine restart
or session log off.
Event: 'unresponsive'
Emitted when the web page becomes unresponsive.
Event: 'responsive'
Emitted when the unresponsive web page becomes responsive again.
Event: 'blur'
Emitted when the window loses focus.
Event: 'focus'
Emitted when the window gains focus.
Event: 'show'
Emitted when the window is shown.
Event: 'hide'
Emitted when the window is hidden.
Event: 'ready-to-show'
Emitted when the web page has been rendered (while not being shown) and window can be displayed without
a visual flash.
Please note that using this event implies that the renderer will be considered "visible" and
paint even though show
is false. This event will never fire if you use paintWhenInitiallyHidden: false
Event: 'maximize'
Emitted when window is maximized.
Event: 'unmaximize'
Emitted when the window exits from a maximized state.
Event: 'minimize'
Emitted when the window is minimized.
Event: 'restore'