API reference

Search queries

Search queries can be passed to screen.find, screen.findAll, screen.waitFor and screen.on interchangeably. Currently, there are no queries which are exclusive to one of these methods, they are processed the same across all methods.


An Image can be passed to screen.find and friends to perform on-screen image search for the provided template image.

It requires an ImageFinder to be registered.


singleWord is a query which is processed by a TextFinder. This query works on word level and tries to locate a single word on screen, delimited by spaces.


textLine is also processed by a TextFinder. This query works on line level, so it'll try to detect matches on a single line of text on screen.


Let's look at an example to talk about this query in detail.

Given the following OCR result of multi-line text:

This is a sample text
extracted from screen.
It should serve as a
sample to explain how
textLine queries work.

Now let's say we pass the following textLine query to screen.findAll:

const textQuery = textLine("a sample");

When running this query, screen.findAll will return the bounding box of a sample in the first line of our sample, but not the second occurrence of these words, since they are not on the same line.


pixelWithColor is a query that takes an RGBA value and searches the screen for a pixel with matching color.


windowWithTitle is a query that takes either a string or a regular expression to search for a window with a particular title.

Data Types