Core Concepts

Window Management

Control application windows — get properties, move, resize, focus, minimize, and restore.

What you can do

Window Properties

Get the title and screen region of any window

window.title, window.region

Move & Resize

Reposition and resize windows programmatically

window.move(), window.resize()

Focus & State

Focus, minimize, and restore windows

window.focus(), window.minimize()

Quick Reference

getActiveWindow

getActiveWindow()

Promise<Window>

Get the currently focused window

getWindows

getWindows()

Promise<Window[]>

Get all open windows

title

window.title

Promise<string>

Get the window title

region

window.region

Promise<Region>

Get the window region, clamped to screen boundaries

move

window.move(newOrigin: Point)

Promise<void>

Move the window to a new position

resize

window.resize(newSize: Size)

Promise<void>

Resize the window

focus

window.focus()

Promise<void>

Bring the window to the foreground

minimize

window.minimize()

Promise<void>

Minimize the window

restore

window.restore()

Promise<void>

Restore a minimized window

Full API Reference

View complete window module documentation with all methods and options

Getting Windows

Use getActiveWindow() to get the currently focused window or getWindows() to list all open windows.

typescript

import { getActiveWindow, getWindows } from "@nut-tree/nut-js";

// Get the currently focused window
const activeWindow = await getActiveWindow();
console.log(await activeWindow.title);

// Get all open windows
const allWindows = await getWindows();
for (const window of allWindows) {
    console.log(await window.title);
}

Window Properties

Every window exposes its title and screen region. The region is automatically clamped to screen boundaries, so you always get valid coordinates even for partially off-screen or maximized windows.

typescript

import { getActiveWindow } from "@nut-tree/nut-js";

const window = await getActiveWindow();

// Get the window title
const title = await window.title;
console.log(`Window: ${title}`);

// Get the window region (clamped to screen boundaries)
const region = await window.region;
console.log(`Position: ${region.left}, ${region.top}`);
console.log(`Size: ${region.width}x${region.height}`);

Screen Boundary Clamping

The region property automatically clamps coordinates to screen boundaries. If a window extends beyond the screen edge (e.g. a maximized window with negative offsets), the returned region is adjusted so all values stay within visible screen space.

Moving & Resizing

Reposition or resize windows by providing a target point or size.

Moving a Window

typescript

import { getActiveWindow } from "@nut-tree/nut-js";

const window = await getActiveWindow();

// Move window to the top-left corner
await window.move({ x: 0, y: 0 });

// Move to a specific position
await window.move({ x: 200, y: 100 });

Resizing a Window

typescript

import { getActiveWindow } from "@nut-tree/nut-js";

const window = await getActiveWindow();

// Resize to specific dimensions
await window.resize({ width: 800, height: 600 });

// Resize to half the screen
import { screen } from "@nut-tree/nut-js";
const screenWidth = await screen.width();
const screenHeight = await screen.height();
await window.resize({ width: screenWidth / 2, height: screenHeight / 2 });

Focus, Minimize & Restore

Control a window's visibility state — bring it to the foreground, minimize it, or restore it from a minimized state.

typescript

import { getActiveWindow, getWindows } from "@nut-tree/nut-js";

const windows = await getWindows();
const targetWindow = windows[0];

// Bring window to the foreground
await targetWindow.focus();

// Minimize the window
await targetWindow.minimize();

// Restore a minimized window
await targetWindow.restore();

Examples

Tile Window to Left Half

Snap the active window to the left side of the screen

Scenario: You want to tile the active window to the left half of the screen.

typescript

import { getActiveWindow, screen } from "@nut-tree/nut-js";

const screenWidth = await screen.width();
const screenHeight = await screen.height();

const window = await getActiveWindow();

// Snap to left half of the screen
await window.move({ x: 0, y: 0 });
await window.resize({ width: screenWidth / 2, height: screenHeight });

Screenshot Active Window

Capture only the active window's region

Scenario: You want to take a screenshot of just the active window, not the entire screen.

typescript

import { getActiveWindow, screen, saveImage } from "@nut-tree/nut-js";

const window = await getActiveWindow();
const windowRegion = await window.region;

// Capture only the window area
const screenshot = await screen.capture(windowRegion);
await saveImage(screenshot, "window-capture.png");

Next Steps

Windows also support searching for UI elements using accessibility APIs. Learn about element queries, waiting for elements, and find hooks:

Element Search

Find UI elements using accessibility APIs and element queries

Clipboard

Read and write clipboard content for copy-paste automation

Text Search (OCR)

Find and read text on screen using optical character recognition