Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 ยท Main and Renderer Processes

BrowserWindow Options and WebPreferences

Configure Electron windows with BrowserWindow options: size, position, show, backgroundColor, webPreferences, preload, sandbox, and avoid the white flash with ready-to-show.

BrowserWindow is the class that creates and controls a native window. Its constructor takes an options object with dozens of settings, but a handful cover most apps. This lesson goes through the important ones, the webPreferences sub-object that controls what the page is allowed to do, and the small details that make a window feel polished.

The common options

JavaScript
const { BrowserWindow } = require('electron')
const path = require('node:path')

const win = new BrowserWindow({
  width: 1000,
  height: 700,
  minWidth: 600,
  minHeight: 400,
  x: 100,
  y: 80,
  title: 'My App',
  backgroundColor: '#0f172a',
  show: false,
  resizable: true,
  webPreferences: {
    preload: path.join(__dirname, '../preload/preload.js'),
    contextIsolation: true,
    nodeIntegration: false,
    sandbox: true,
  },
})
Option What it does
width, height Initial content size in device-independent pixels (the window frame is added on top, unless you set useContentSize: false)
minWidth, minHeight, maxWidth, maxHeight Limits when the user resizes
x, y Position on screen; omit to let the OS pick, or use center: true
title Window title (the page's <title> overrides it unless you cancel page-title-updated)
backgroundColor Color shown before the page paints; match your page to avoid a flash
show false creates the window hidden
resizable, movable, minimizable, maximizable, closable, fullscreenable Turn user actions on or off
alwaysOnTop Keeps the window above others
icon Window icon on Windows and Linux
parent, modal Make a child or modal window (window management)
frame, titleBarStyle Frameless and custom title bars
webPreferences How the page runs (below)

Avoid the white flash: ready-to-show

When a window is created and shown immediately, users see a blank white rectangle until the page paints. Create it hidden, then show it when the renderer has drawn its first frame:

JavaScript
const win = new BrowserWindow({ show: false, backgroundColor: '#0f172a' })

win.once('ready-to-show', () => {
  win.show()
})

win.loadFile('index.html')

Setting backgroundColor to match your page also helps when the window is resized quickly.

webPreferences: what the page may do

webPreferences is where security and capabilities are decided. The important keys:

Key Recommended Why
preload absolute path to a script Runs before the page; exposes a safe API with contextBridge
contextIsolation true (default) Keeps your preload's world apart from the page's world
nodeIntegration false (default) Prevents page code from using Node.js
sandbox true (default) Limits the renderer's OS privileges
webSecurity true (default) Never disable it; it enforces the same-origin policy
devTools true in dev, consider false in production Enables DevTools
spellcheck true Spellcheck in text inputs
backgroundThrottling true (default) Slows timers in hidden windows; set false only if you need background work
zoomFactor 1.0 Initial page zoom

The first line of defence is simply not overriding the safe defaults. Many old guides disable them to make a tutorial shorter; do not copy that.

A preload path must be absolute. path.join(__dirname, 'preload.js') is the safe pattern. A relative path resolves against the process working directory, so it silently fails when you launch the app from somewhere else, and your page then has no window.electronAPI at all.

Defaults as code

You can model option merging yourself, which is what Electron does internally: your options are layered over defaults. This stand-in builds an options object, applies defaults and rejects unsafe overrides so you can see a review rule in executable form.

Node.js Stand-in: merging options and a safety check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Useful window methods and events

After creating a window you control it with methods:

JavaScript
win.show(); win.hide(); win.focus()
win.minimize(); win.maximize(); win.unmaximize(); win.restore()
win.setFullScreen(true)
win.setSize(1200, 800); win.center()
win.setTitle('Report.pdf')
win.setProgressBar(0.5)           // taskbar or dock progress
win.setAlwaysOnTop(true)
win.close()                       // asks the window to close (fires 'close')
win.destroy()                     // forces it, no 'close' event

Common events: ready-to-show, show, hide, focus, blur, resize, move, maximize, close (can be prevented with event.preventDefault()) and closed (the window is gone; drop your references).

Keep a reference to every window in a variable or a Map. If you only store a window in a local variable of a function, the JavaScript garbage collector can destroy it and the window closes on its own.

Remembering size and position

Users expect an app to reopen where they left it. Save the window's getBounds() when it moves or resizes (debounced) and on close, then pass them to the constructor next time. The following stand-in debounces writes and validates that a saved position is still on a connected display, which matters when a monitor is unplugged.

Node.js Stand-in: remember window bounds

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you avoid showing a blank white window while the page loads?

    Hidden creation plus ready-to-show means the window appears only after the first paint; backgroundColor smooths resizes.
  2. 2. Which webPreferences preload path is correct?

    The preload path must be absolute; __dirname-based paths do not depend on the working directory.
  3. 3. What can happen if you keep a BrowserWindow only in a function's local variable?

    Without a lasting reference the object can be collected, closing the window; store windows in a longer-lived variable or Map.
  4. 4. Which event fires when the window has been destroyed so you should drop references?

    close can be prevented and fires before closing; closed fires after the window is gone.

Summary

  • BrowserWindow options control size, position, behavior and look; webPreferences controls what the page may do.
  • Keep contextIsolation, sandbox and webSecurity on and nodeIntegration off.
  • Use show: false with ready-to-show and a matching backgroundColor for a clean launch.
  • Preload paths must be absolute.
  • Keep window references alive, and clear them on closed.
  • Save and validate bounds to reopen windows where users left them.

Next: Processes, WebContents and Utility Processes