Core Concepts

Screen

Work with screen dimensions, capture screenshots, and understand regions for automation.

What you can do

Screen Dimensions

Get screen width and height for positioning calculations

screen.width(), screen.height()

Screenshots

Capture the entire screen or specific regions

screen.capture()

Regions

Define rectangular areas for targeted operations

new Region(x, y, width, height)

Quick Reference

width

screen.width()

Promise<number>

Get the screen width in pixels

height

screen.height()

Promise<number>

Get the screen height in pixels

capture

screen.capture(region?: Region)

Promise<Image>

Capture a screenshot of the entire screen or a specific region

Full API Reference

View complete screen module documentation with all methods and options

Screen Dimensions

Get the screen dimensions to position elements, calculate relative coordinates, or determine where UI elements should appear.

typescript

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

// Get screen dimensions
const width = await screen.width();
const height = await screen.height();
console.log(`Screen size: ${width}x${height}`);

// Move to center of screen
await mouse.move(straightTo({
    x: width / 2,
    y: height / 2
}));

// Move to bottom-right corner
await mouse.move(straightTo({
    x: width - 10,
    y: height - 10
}));

Multi-Monitor Support

On multi-monitor setups, screen.width() and screen.height() return the dimensions of the primary display. Screen coordinates may extend beyond these values on secondary monitors.

Capturing Screenshots

Capture screenshots of the entire screen or specific regions for debugging, logging, visual comparison, or creating reference images for search operations.

Full Screen Capture

typescript

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

// Capture the entire screen
const screenshot = await screen.capture();

// Save to file
await saveImage(screenshot, "screenshot.png");

// Access image properties
console.log(`Captured image: ${screenshot.width}x${screenshot.height}`);

Region Capture

Capture only a specific portion of the screen by passing a Region.

typescript

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

// Define a region (left, top, width, height)
const region = new Region(100, 100, 400, 300);

// Capture only that region
const partialCapture = await screen.capture(region);

// Save the cropped screenshot
await saveImage(partialCapture, "region-capture.png");

Use Cases for Screenshots

Create reference images for image search operations
Debug automation scripts by capturing state at each step
Generate visual logs of automation runs
Compare expected vs actual screen states

Working with Regions

Regions define rectangular areas on the screen. They are fundamental to nut.js and used throughout the API for targeting specific areas, limiting search scopes, and capturing partial screenshots.

Creating Regions

typescript

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

// Create a region with constructor (left, top, width, height)
const region = new Region(100, 100, 400, 300);

// Region properties
console.log(region.left);   // 100 - X coordinate of top-left corner
console.log(region.top);    // 100 - Y coordinate of top-left corner
console.log(region.width);  // 400 - Width of the region
console.log(region.height); // 300 - Height of the region

Creating Regions from Coordinates

typescript

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

// If you have corner coordinates instead of width/height
const topLeft = { x: 100, y: 100 };
const bottomRight = { x: 500, y: 400 };

const region = new Region(
    topLeft.x,
    topLeft.y,
    bottomRight.x - topLeft.x,  // width = 400
    bottomRight.y - topLeft.y   // height = 300
);

Region Helper Functions

nut.js provides helper functions to work with regions.

typescript

import { centerOf, Region } from "@nut-tree/nut-js";

const region = new Region(100, 100, 400, 300);

// Get the center point of a region
const center = centerOf(region);
console.log(`Center: ${center.x}, ${center.y}`);
// Center: 300, 250

Regions in Search Operations

Regions are heavily used in on-screen search operations to limit the search area. Searching within a small region is significantly faster than searching the entire screen. See the Image Search documentation for details.

Examples

Responsive Positioning

Position elements relative to screen size

Scenario: You need to click a button that's always in the bottom-right corner.

typescript

import { screen, mouse, straightTo, Button } from "@nut-tree/nut-js";

// Get screen dimensions
const width = await screen.width();
const height = await screen.height();

// Click 50 pixels from the bottom-right corner
await mouse.move(straightTo({
    x: width - 50,
    y: height - 50
}));
await mouse.click(Button.LEFT);

Screenshot Logging

Capture screenshots at each automation step

Scenario: You want to debug an automation by saving screenshots at key points.

typescript

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

async function logStep(stepName: string) {
    const timestamp = Date.now();
    const screenshot = await screen.capture();
    await saveImage(screenshot, `logs/${timestamp}-${stepName}.png`);
    console.log(`Logged: ${stepName}`);
}

// Use during automation
await logStep("before-login");
// ... perform login actions
await logStep("after-login");
// ... perform more actions
await logStep("completed");

Dynamic Region Definition

Create regions based on screen proportions

Scenario: You want to define a search region that works across different screen sizes.

typescript

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

// Create a region that's always the left third of the screen
const width = await screen.width();
const height = await screen.height();

const leftSidebar = new Region(
    0,              // left edge
    0,              // top edge
    width / 3,      // one-third of screen width
    height          // full height
);

// Now use this region for searches or captures
const sidebarCapture = await screen.capture(leftSidebar);

Next Steps

Now that you understand the screen basics, learn about the different ways to search for content on screen:

Image Search

Find UI elements by searching for reference images

Text Search (OCR)

Find and read text on screen using optical character recognition

Element Search

Find UI elements using accessibility APIs

Color Search

Find pixels and regions by color