Methods

• Keyboard
  • Keys
  • setKeyboardDelay
  • keyTap
  • keyToggle
  • unicodeTap
  • typeString
  • typeStringDelayed
• Mouse
  • setMouseDelay
  • moveMouse
  • moveMouseSmooth
  • mouseClick
  • mouseToggle
  • dragMouse
  • getMousePos
  • scrollMouse
• Screen
  • getPixelColor
  • getScreenSize
  • getDisplays
  • updateScreenMetrics
  • screen.capture
• Image
  • Image file I/O
  • Properties
  • Search options
  • Color search
  • Image search
  • Coordinate conversion and clicks

Keyboard

Keys

keyToggle and keyTap support for following keys.

Note: The names of the letter and number keys are the same as that single letter or digit. For example: b is the “b” key and 5 is the “5” key.

Key list up to date as of RobotJS v0.8.x.

setKeyboardDelay(ms)

Sets the delay in milliseconds to sleep after a keyboard event. This is 10ms by default.

Arguments

keyTap(key, [modifier])

Press a single key.

Arguments

keyToggle(key, down, [modifier])

Hold down or release a key.

Arguments

unicodeTap(value)

Presses and releases one Unicode code point.

Arguments

typeString(string)

Types a string. On Linux, RobotJS 0.8 automatically applies the Shift or AltGr modifier required by the active keyboard layout.

Arguments

typeStringDelayed(string, cpm)

Types a string at a controlled rate.

Arguments

Mouse

setMouseDelay(ms)

Sets the delay in milliseconds to sleep after a mouse event. This is 10ms by default.

Arguments

moveMouse(x, y)

Moves mouse to x, y instantly, with the mouse button up.

Arguments

Examples

const robot = require("robotjs");

// Move the mouse to 100, 100 on the screen.
robot.moveMouse(100, 100);

moveMouseSmooth(x, y, [speed])

Moves the mouse to x, y along a human-like path, with the mouse button up.

Arguments

mouseClick([button], [double])

Clicks the mouse.

Arguments

Examples

const robot = require("robotjs");

robot.mouseClick();

mouseToggle([down], [button])

Toggles mouse button.

Arguments

Examples

const robot = require("robotjs");

robot.mouseToggle("down");

setTimeout(() => {
    robot.mouseToggle("up");
}, 2000);

dragMouse(x, y)

Moves mouse to x, y instantly, with the mouse button held down.

Arguments

Examples

const robot = require("robotjs");

// Mouse down at 0, 0, then drag to 100, 100 and release.
robot.moveMouse(0, 0);
robot.mouseToggle("down");
robot.dragMouse(100, 100);
robot.mouseToggle("up");

getMousePos()

Gets the mouse coordinates.

Return

Returns an object with keys x and y.

Examples

const robot = require("robotjs");

const mouse = robot.getMousePos();
console.log(`Mouse is at x:${mouse.x} y:${mouse.y}`);

scrollMouse(x, y)

Scrolls the mouse in any direction.

Arguments

Examples

const robot = require("robotjs");

robot.scrollMouse(50, 0);

setTimeout(() => {
    robot.scrollMouse(50, 0);
}, 2000);

Screen

getPixelColor(x, y)

Gets one pixel from the main display. Use an Image search when reading a larger area.

Arguments

Return

Returns the pixel’s six-digit hexadecimal RGB color without a leading #.

getScreenSize()

Gets the main display’s logical width and height.

Return

Returns an object with .width and .height.

getDisplays()

Gets all active displays. Coordinates are signed desktop coordinates, so a display above or to the left of the main display can have a negative origin.

Return

Returns an array of display objects.

updateScreenMetrics()

Refreshes RobotJS’s cached screen metrics after the display arrangement or resolution changes.

screen.capture([x], [y], [width], [height])

Captures the main display or a rectangle contained by one active display.

Arguments

Pass either no arguments or all four arguments. A capture rectangle must stay inside one display; it cannot span displays.

Return

Returns an Image. Captures include screenX, screenY, scaleX, and scaleY, so image coordinates can be converted back to logical screen coordinates on high-density displays.

Example

const robot = require("robotjs");

const secondary = robot.getDisplays().find((display) => !display.isMain);

if (secondary) {
    const image = robot.screen.capture(
        secondary.x,
        secondary.y,
        secondary.width,
        secondary.height
    );
    image.save("./secondary-display.bmp");
}

Image

An Image is returned by screen.capture or robot.image.load. robot.Bitmap remains an alias for robot.Image.

robot.image.load(path)

Loads a .bmp or .png file and returns an Image. BMP is always supported. PNG requires a PNG-enabled build; check robot.image.supportsPNG first.

robot.image.save(image, path)

Saves an Image. The .bmp or .png file extension selects the output format. Returns true on success.

robot.image.supportsPNG

A boolean indicating whether this RobotJS build can load and save PNG files. See Building to enable PNG support in a source build.

Properties

Search options

Color and image search methods accept the same optional object.

The search rectangle must remain inside the Image.

colorAt(x, y)

Returns the six-digit hexadecimal RGB color at an image point without a leading #.

findColor(color, [options])

Returns the first matching { x, y } image point, or null. color accepts RRGGBB or #RRGGBB.

findColors(color, [options])

Returns every matching { x, y } image point, or an empty array.

countColor(color, [options])

Returns the number of matching pixels.

findImage(needle, [options])

Returns the top-left { x, y } image point of the first matching Image, or null.

findImages(needle, [options])

Returns the top-left image points of every match, including overlapping matches, or an empty array.

countImage(needle, [options])

Returns the number of image matches, including overlapping matches.

Example

const robot = require("robotjs");

const screen = robot.screen.capture();
const target = robot.image.load("./target.bmp");
const match = screen.findImage(target, { tolerance: 0.1 });

if (match) {
    screen.click(match, target);
}

Search methods return image-space coordinates. A screen capture’s click helpers account for its display origin and pixel density.

save(path)

Saves this Image as .bmp or .png and returns true on success. This is equivalent to robot.image.save(image, path).

toScreenPoint(point, [target])

Converts an image-space point to a logical screen point. When target supplies width and height, the returned point is centered within that target.

click(point, [target], [button], [double])

Moves the mouse to an image point and clicks it. Pass the matched target as target to click its center. button accepts left, right, or middle; double defaults to false. Returns the logical screen point that was clicked.

clickImage(target, [options], [button], [double])

Finds target and clicks its center. Returns the match’s top-left image point, or null without moving or clicking when no match is found.

• Getting Started
• Examples
• Syntax
• Building
• FAQ
• Electron