Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shadownrx/windows/llms.txt

Use this file to discover all available pages before exploring further.

useWindowManager is the most important hook in NEX OS — it exposes the complete window lifecycle API for opening, closing, minimizing, maximizing, snapping, and focusing windows. It acts as the kernel of the operating system, coordinating z-index management, virtual desktop assignments, snap layouts, and state preservation across every window instance.

​
Import

import { useWindowManager } from '../context/WindowManager';

​
AppWindow Interface

Every managed window is represented as an AppWindow object in the global windows array. 
interface AppWindow {
  id: string;
  title: string;
  icon: ReactNode;
  content: ReactNode;
  desktopId: string;
  isOpen: boolean;
  isMinimized: boolean;
  isMaximized: boolean;
  snap?: 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'none';
  zIndex: number;
  savedSize?: { width: number; height: number; x: number; y: number };
}
​
id
string
required
Unique window identifier. Used as the primary key for all window operations — pass this to closeWindow, focusWindow, snapWindow, and so on.
​
title
string
required
Text rendered in the window’s title bar.
​
icon
ReactNode
required
Icon displayed alongside the title in both the title bar and the taskbar button.
​
content
ReactNode
required
The actual application component rendered inside the window frame. Wrap heavy apps in React.memo to prevent unnecessary re-renders when zIndex changes.
​
desktopId
string
required
The virtual desktop this window belongs to. Windows are only rendered when their desktopId matches the currently active desktop.
​
isOpen
boolean
required
Whether the window is currently visible on screen. A window can exist in state but not be open (e.g., while minimized).
​
isMinimized
boolean
required
true when the window has been sent to the taskbar. The window’s internal React state is fully preserved — use restoreWindow to bring it back without reinitializing.
​
isMaximized
boolean
required
true when the window occupies the full viewport. The previous size and position are saved to savedSize before maximizing.
​
snap
'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'none'
The active snap position. 'none' or undefined means the window is freely positioned.
​
zIndex
number
required
Stacking layer order. Managed automatically by focusWindow — the focused window always receives the highest zIndex.
​
savedSize
{ width: number; height: number; x: number; y: number }
Stores the window’s dimensions and position captured just before maximizing. Restored when the user un-maximizes, ensuring the window returns to exactly where it was.

​
Properties

​
windows
AppWindow[]
The live array of all window instances — both open and minimized. Subscribe to this to render taskbar buttons or check for existing windows before launching a new one.
​
focusedWindowId
string | null
The id of the window that currently has focus. null when no window is active (e.g., the desktop itself is focused). Used by closeFocusedWindow to implement Alt+F4.

​
Methods

​
openWindow

Opens a new window, or restores and focuses the window if one with the same id already exists in state.
​
id
string
required
Unique identifier for the window. If a window with this id already exists, openWindow will restore it instead of creating a duplicate.
​
title
string
required
Display text for the window title bar.
​
icon
ReactNode
required
Icon shown in the title bar and taskbar.
​
content
ReactNode
required
The application component to render inside the window.

​
closeWindow

Closes the window and removes it entirely from the windows state array.
​
id
string
required
The ID of the window to close and destroy.

​
minimizeWindow

Sends the window to the taskbar. The window’s internal React state is frozen in place — nothing is unmounted.
​
id
string
required
The ID of the window to minimize.

​
minimizeAllWindows

Minimizes every open window at once. Bound to the Win+D keyboard shortcut. Equivalent to calling minimizeWindow on each entry in windows.

​
maximizeWindow

Toggles the maximized state of a window. When maximizing, the current dimensions and coordinates are written to savedSize so they can be restored precisely later.
​
id
string
required
The ID of the window to maximize or un-maximize.
​
currentSize
{ width: number; height: number; x: number; y: number }
The window’s current size and position. Pass this so savedSize captures the exact geometry before the window goes fullscreen.

​
restoreWindow

Brings a minimized window back to the screen without reinitializing its content. This is the key difference from openWindow — the app component is not remounted, so all internal state (scroll position, text inputs, media playback) is preserved.
​
id
string
required
The ID of the minimized window to restore.

​
snapWindow

Docks the window to a screen region. The Window HOC applies the corresponding CSS layout (half-screen, quadrant, etc.) based on the direction value.
​
id
string
required
The ID of the window to snap.
​
direction
'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'none'
required
The target snap region. Pass 'none' to release the window from a snapped position.

​
focusWindow

Brings a window to the front by assigning it the highest zIndex value and updating focusedWindowId.
​
id
string
required
The ID of the window to bring into focus.

​
closeFocusedWindow

Closes whichever window is currently focused (focusedWindowId). This is the handler for the global Alt+F4 keyboard shortcut.

​
Usage Example

import { useWindowManager } from '../context/WindowManager';
import MiApp from './apps/MiApp';

export const LauncherButton = () => {
  const { openWindow, restoreWindow, windows } = useWindowManager();

  const handleClick = () => {
    const existing = windows.find(w => w.id === 'mi-app');
    if (existing?.isMinimized) {
      restoreWindow('mi-app');
    } else {
      openWindow('mi-app', 'Mi App', <span>🚀</span>, <MiApp />);
    }
  };

  return <button onClick={handleClick}>Open App</button>;
};

​
Best Practices

Always check windows.find(w => w.id === 'your-id') before calling openWindow. If the window already exists, call restoreWindow instead — this preserves the app’s internal React state and avoids remounting the component tree.
Wrap any heavy application component in React.memo before passing it as content. The WindowManager updates zIndex on every focus change, which triggers re-renders of the entire windows array. React.memo prevents unnecessary work in apps that don’t need to respond to those updates.
const HeavyApp = React.memo(() => {
  return <div>Expensive content…</div>;
});

openWindow('heavy', 'Heavy App', <Icon />, <HeavyApp />);
Always pass currentSize when calling maximizeWindow so that savedSize captures the exact position before the window goes fullscreen:
const { maximizeWindow } = useWindowManager();

const handleMaximize = () => {
  maximizeWindow(windowId, {
    width: size.width,
    height: size.height,
    x: pos.x,
    y: pos.y,
  });
};
useWindowManager must be called inside a component that is a descendant of WindowManagerProvider. Calling it outside the provider tree throws an error.

Build docs developers (and LLMs) love

Get started for freeTalk to us