Hooks

All hooks must be called inside a <Window>’s children.

useCurrentWindow()

Returns a WindowHandle with stable imperative methods. References don’t change identity across renders.

function WindowContent() {
  const win = useCurrentWindow();

  win.focus();
  win.close();
  win.setBounds({ width: 800, height: 600 });
}

WindowHandle state

Read-only snapshots. The handle object identity changes when these change — don’t use the whole handle as an effect dependency.

Field	Type	Description
id	string	The window ID
isReady	boolean	false until the window is created and content mounted. Methods are no-ops until this is true.
isFocused	boolean	Window has focus
isMaximized	boolean	Window is maximized
isMinimized	boolean	Window is minimized
isFullscreen	boolean	Window is fullscreen
bounds	Bounds	Current { x, y, width, height }

WindowHandle methods

Method references are stable across renders — safe to pass as effect dependencies or event handlers.

Method	Description
focus()	Focus the window
blur()	Unfocus the window
close()	Close the window (respects closable)
forceClose()	Force close (bypasses closable)
minimize()	Minimize the window
maximize()	Maximize the window
unmaximize()	Restore from maximized
toggleMaximize()	Toggle maximize state
setBounds(bounds)	Set { x, y, width, height }
setTitle(title)	Set the window title
enterFullscreen()	Enter fullscreen mode
exitFullscreen()	Exit fullscreen mode

useIsInsideWindow()

Returns true if the component is rendering inside a <Window>’s children, false otherwise. Unlike the other hooks, this doesn’t throw when called outside a <Window> — use it to conditionally render components that call useCurrentWindow() and friends.

function StatusBar() {
  const inside = useIsInsideWindow();
  if (!inside) return <span>Main window</span>;
  const focused = useWindowFocused(); // safe — we checked
  return <span>{focused ? "Focused" : "Blurred"}</span>;
}

Reactive State Hooks

Each hook re-renders only when its specific value changes.

Hook	Return Type	Description
useWindowFocused()	boolean	Whether the window has focus
useWindowMaximized()	boolean	Whether the window is maximized
useWindowMinimized()	boolean	Whether the window is minimized
useWindowFullscreen()	boolean	Whether in fullscreen mode
useWindowVisible()	boolean	Whether the window is visible
useWindowBounds()	{ x: number; y: number; width: number; height: number }	Current bounds
useWindowDisplay()	DisplayInfo | null	Current display — null until the window has moved at least once
useWindowState()	WindowState | null	Full window state object — null before the window is ready
useWindowDocument()	Document | null	The child window’s Document (see Integration Notes)

DisplayInfo has the shape { id: number; bounds: Bounds; workArea: Bounds; scaleFactor: number }.

function WindowContent() {
  const isFocused = useWindowFocused();
  const isMaximized = useWindowMaximized();
  const isMinimized = useWindowMinimized();
  const isFullscreen = useWindowFullscreen();
  const isVisible = useWindowVisible();
  const bounds = useWindowBounds();     // { x, y, width, height }
  const display = useWindowDisplay();   // { id, bounds, workArea, scaleFactor }
  const state = useWindowState();       // full WindowState object
}

Use the specific hooks (useWindowFocused, useWindowBounds, etc.) rather than useWindowState when possible — they avoid unnecessary re-renders.

Cleanup on close

Components inside a <Window> often attach listeners or start fetches against the child document. Those need cleanup when the window closes — otherwise the listener retains the closed window’s Document.

useWindowEventListener(type, handler, options?)

Attaches an event listener to the child window’s document that’s automatically removed when the window closes or releases back to its pool. The handler can be an inline arrow — it’s read through a ref, so re-renders don’t re-subscribe.

import { useWindowEventListener } from "@loc/electron-window";

function WindowContent({ onClose }) {
  useWindowEventListener("keydown", (e) => {
    if (e.key === "Escape") onClose();
  });
  // No cleanup needed — listener is removed on window close.
}

useWindowSignal()

Returns an AbortSignal that fires when the window closes. Pass to addEventListener, fetch, MutationObserver, etc. for automatic cleanup.

Caution

The signal is window-scoped, not component-scoped. If your component may unmount while the window stays open (e.g., it’s conditionally rendered inside a <Window>), the signal-only pattern leaks — you still need a useEffect cleanup return. Prefer useWindowEventListener which handles both cases.

import { useWindowSignal, useWindowDocument } from "@loc/electron-window";

function WindowContent() {
  const signal = useWindowSignal();
  const doc = useWindowDocument();

  useEffect(() => {
    const obs = new ResizeObserver(handleResize);
    obs.observe(doc.body);
    signal.addEventListener("abort", () => obs.disconnect());
    doc.addEventListener("visibilitychange", onVis, { signal });
    // Still return cleanup for COMPONENT unmount — the signal only
    // fires on WINDOW close. Without this, a conditionally-rendered
    // child that unmounts leaves its observer/listener attached.
    return () => {
      obs.disconnect();
      doc.removeEventListener("visibilitychange", onVis);
    };
  }, [signal, doc]);
}

For pooled windows, the signal is per-acquisition — aborted on release even though the underlying BrowserWindow stays alive for the next consumer.

usePersistedBounds(key, defaults)

For manual bounds persistence. See Persistence for full usage.

const { bounds, save, clear } = usePersistedBounds("my-window", {
  defaultWidth: 800,
  defaultHeight: 600,
});

Return value	Type	Description
bounds	{ defaultWidth?, defaultHeight?, defaultX?, defaultY? }	Saved bounds (mapped to default* prop names) or the defaults you passed. Spread directly into <Window>.
save	(bounds: Bounds) => void	Persist current bounds. Debounced (default 500ms).
clear	() => void	Remove saved bounds

The bounds keys are defaultWidth/defaultHeight/defaultX/defaultY — not width/height/x/y — so that {...bounds} spreads cleanly onto <Window> without accidentally creating a controlled window.