Props Reference

Lifecycle

Prop	Type	Default	Description
open	boolean	required	Whether the window exists. false destroys it.
visible	boolean	true	Show/hide without destroying. State is preserved.
closable	boolean	true	Whether the user can close the window.
onUserClose	() => void	—	User clicked X. Fires once; sync your state here.
onClose	() => void	—	Window destroyed (any reason: user, programmatic, unmount).
onReady	() => void	—	Window ready and content mounted.

open controls existence. visible controls visibility. open={true} visible={false} creates a hidden window with state preserved. open={false} destroys everything.

Geometry

Prop	Type	Description
defaultWidth / defaultHeight	number	Initial size. Applied once on creation. User can resize freely.
defaultX / defaultY	number	Initial position. Applied once on creation.
width / height	number	Controlled size. Changes resize the window. Use with onBoundsChange.
x / y	number	Controlled position. Changes move the window.
onBoundsChange	(bounds) => void	Fires on resize/move. Debounced internally (100ms).
minWidth / maxWidth	number	Size constraints.
minHeight / maxHeight	number	Size constraints.
center	boolean	Center on creation. Default true when no position specified.

The default* / controlled split follows React’s defaultValue / value pattern. Use defaultWidth for fire-and-forget sizing, width + onBoundsChange for two-way sync.

Appearance

Prop	Type	Default	Description
title	string	""	Window title.
transparent	boolean	false	Transparent background. Creation-only.
frame	boolean	true	Show window chrome. Creation-only.
titleBarStyle	string	—	"hidden", "hiddenInset", etc. Creation-only.
vibrancy	string	—	macOS vibrancy effect. Creation-only.
backgroundColor	string	—	Background color.
opacity	number	—	Window opacity (0.0–1.0).

Creation-only props cannot change after the window is created. Changing them logs a dev warning. Set recreateOnShapeChange to destroy and recreate the window instead — note that this unmounts and remounts all children, so any useState/useRef inside them resets.

open={false} and unload listeners

Setting open={false} destroys the window via BrowserWindow.destroy(), which does not fire beforeunload/unload. If you attach those listeners via useWindowDocument(), they’ll fire on user-initiated close (X button) but not on programmatic close.

Behavior

Prop	Type	Default
resizable	boolean	true
movable	boolean	true
minimizable	boolean	true
maximizable	boolean	true
focusable	boolean	true
alwaysOnTop	boolean | AlwaysOnTopLevel	false
skipTaskbar	boolean	false
fullscreen	boolean	false
fullscreenable	boolean	true
showInactive	boolean	false
ignoreMouseEvents	boolean	false
visibleOnAllWorkspaces	boolean	false

AlwaysOnTopLevel is a string union: "normal" | "floating" | "torn-off-menu" | "modal-panel" | "main-menu" | "status" | "pop-up-menu" | "screen-saver". Higher levels float above lower ones. true is equivalent to "floating".

Events

Prop	Fires when
onFocus	Window gains focus
onBlur	Window loses focus
onMaximize / onUnmaximize	Maximize state changes
onMinimize / onRestore	Minimize state changes
onEnterFullscreen / onExitFullscreen	Fullscreen changes
onDisplayChange	Window moves to a different monitor
onBoundsChange	Window resized or moved

Platform

Prop	Platform	Description
trafficLightPosition	macOS	{ x, y } for close/minimize/maximize buttons
titleBarOverlay	Windows	{ color, symbolColor, height }
targetDisplay	all	"primary", "cursor", or display index. Centers the window on that display when no explicit x/y.

Advanced

Prop	Type	Default	Description
persistBounds	string	—	Unique key. Saves bounds to localStorage, restores on reopen.
recreateOnShapeChange	boolean	false	Recreate window when creation-only props change.
name	string	—	Debug label for DevTools and warning messages.
injectStyles	"auto" | false | (doc) => void	"auto"	How to copy styles into the child window. false for CSS-in-JS.

For persistBounds and the usePersistedBounds hook, see Persistence.