Guide · Open source

How to use robotjs: install, control the mouse and keyboard

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

RobotJS is a Node.js library for desktop automation. A script can move the mouse, press keys, type text, read pixel colors, and capture or search the screen, which is useful for tasks that have no API. This guide covers installation, the main examples from the project, and the limits you should know before relying on it.

RobotJSoctalmage/robotjs · ★ 12.8k · MIT Install options & downloads

Quick start

1Install Node.js and npm. Get Node.js from nodejs.org, which includes npm. Confirm both are installed before continuing.
2Install the robotjs package. Run npm install robotjs in your project folder.
3Write a small script. Create a file that requires robotjs and calls a function such as typeString or keyTap.
4Check permissions on macOS. Call the permission functions and approve the system prompts if your script needs mouse, keyboard or screen access.
5Run and test carefully. Start with a harmless action, since the script will control your real mouse and keyboard.
6Build from source if needed. If no prebuild matches your system, install the listed compilers and run node-gyp rebuild.

What RobotJS does and which platforms it supports

RobotJS lets JavaScript code control the mouse and keyboard and read the screen. The README says it supports Mac, Windows, and Linux.

The project describes itself as a work in progress. Exported functions could change at any time before the first stable release, 1.0.0, so pin your versions and expect possible changes.

Mouse: move, click, drag.
Keyboard: press keys, hold keys, type words.
Screen: read pixel colors, capture the screen, find images and colors.
Bitmap: load and save BMP files, with optional PNG support.

Install robotjs with npm

Install RobotJS with npm. You need Node.js, which you can get from nodejs.org, and npm.

Published packages include Node-API prebuilds for Linux, macOS, and Windows on x64 and arm64. On other targets, npm falls back to a source build, which needs the tools described in the building section.

npm install robotjs

Build from source when a prebuild is not available

If you need to build RobotJS, install the platform dependencies first. The README lists these requirements:

Windows: a supported Visual Studio C++ toolchain.
macOS: Xcode Command Line Tools.
Linux: Python 3, make, a C/C++ compiler such as GCC, and libxtst-dev.

npm install -g node-gyp
node-gyp rebuild

Move the mouse, type text and press keys

The mouse example moves the cursor along a sine wave using robot.moveMouse. It calls robot.setMouseDelay to speed up movement. The keyboard example types a string and then presses Enter with robot.keyTap.

Run these scripts only when you are ready for the cursor and keyboard to move on your machine.

const robot = require("robotjs");

// Type "Hello World" then press enter.
robot.typeString("Hello World");
robot.keyTap("enter");

Read pixel colors and search the screen for images

To read a color, get the mouse position with robot.getMousePos, then pass the coordinates to robot.getPixelColor. The result is a hex string.

For image search, capture the screen, load a target image, and call findImage. The README says image searches return the target's top-left capture coordinates, and click converts them to screen coordinates and clicks the target's center. Captured and loaded images also provide findImages, countImage, findColor, findColors, countColor, colorAt, and save.

Use robot.screen.capture() for the main display, or pass x, y, width, height for a rectangle.
Use robot.getDisplays() to inspect displays. A capture rectangle cannot span multiple displays.
Check robot.image.supportsPNG at runtime to see whether PNG is available.

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);
}

Grant macOS permissions

On macOS, control of the mouse and keyboard and screen capture need user approval. Use getAccessibilityPermission() and getScreenCapturePermission() to check the current grants. requestAccessibilityPermission() and requestScreenCapturePermission() trigger the system prompts.

The Accessibility prompt is asynchronous, so requestAccessibilityPermission() returns the current grant. Call getAccessibilityPermission() again after the user responds. The user must approve each request.

What people use it for

Typing repeated text or pressing keys in an app that has no API.
Moving the mouse across the screen on a timed path, as in the sine wave example.
Reading the color under the cursor to check whether a UI state has changed.
Finding a button image on screen and clicking its center.
Capturing a screen region to save as a bitmap file.

Frequently asked questions

Does robotjs support global hotkeys?

No. The project FAQ says RobotJS does not currently support global hotkeys, and the author suggests using Electron or NW.js for them. Hotkey support may come later or in a separate module.

Is robotjs free to use?

RobotJS is released under the MIT license, as stated in the README. The license text is in the repository.

How do I install robotjs?

Run npm install robotjs with Node.js and npm installed. Published packages include prebuilds for Linux, macOS and Windows on x64 and arm64, and other targets fall back to a source build.

Can robotjs take a screenshot?

Yes. robot.screen.capture() captures the main display, and you can pass x, y, width and height to capture a specific rectangle.

Does robotjs support multiple monitors?

Yes, with limits. Use robot.getDisplays() to inspect displays and pass a rectangle from one display to robot.screen.capture. A capture rectangle cannot span multiple displays, and Linux reports the current X11 screen.

What are the alternatives to robotjs?

The project lists nut.js, pyautogui and AutoHotkey as comparable projects. AutoHotkey is a Windows-focused scripting tool, while nut.js is a Node.js option and pyautogui is for Python.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

RobotJS suits Node.js or Electron developers who need simple mouse, keyboard and screen control on Mac, Windows or Linux, especially for image or color matching. Do not pick it if you need global hotkeys, window management or a stable API before 1.0.0, since the README says those are missing or may change.

Install options & downloads