Implementation:Puppeteer Puppeteer Locator And Input API

Knowledge Sources	Puppeteer Puppeteer Locators
Domains	Browser_Automation, User_Simulation
Last Updated	2026-02-11 23:00 GMT

Overview

Concrete tools for interacting with page elements through the Locator API and low-level Keyboard/Mouse classes, provided by the puppeteer-core library.

Description

Puppeteer provides element interaction through multiple classes:

• Locator (locators.ts): High-level, resilient element interaction with auto-waiting, retry logic, and visibility checks. Created via page.locator(selector). Uses RxJS observables internally.
• Keyboard (Input.ts): Low-level keyboard input simulation. Methods: type(), press(), down(), up().
• Mouse (Input.ts): Low-level mouse input simulation. Methods: click(), move(), down(), up(), wheel().

Usage

Use page.locator(selector) for most element interactions. Fall back to page.keyboard and page.mouse for low-level input control.

Code Reference

Source Location

• Repository: puppeteer
• Locator: packages/puppeteer-core/src/api/locators/locators.ts (lines 116-1149)
• Keyboard: packages/puppeteer-core/src/api/Input.ts (lines 170-210)
• Mouse: packages/puppeteer-core/src/api/Input.ts (lines 369-420)

Signature

// Locator API
class Locator<T> {
  click(options?: LocatorClickOptions): Promise<void>;
  fill(value: string, options?: LocatorOptions): Promise<void>;
  hover(options?: LocatorOptions): Promise<void>;
  scroll(options: LocatorScrollOptions): Promise<void>;
}

// Keyboard API
abstract class Keyboard {
  abstract type(text: string, options?: Readonly<KeyboardTypeOptions>): Promise<void>;
  abstract press(key: KeyInput, options?: Readonly<KeyPressOptions>): Promise<void>;
  abstract down(key: KeyInput): Promise<void>;
  abstract up(key: KeyInput): Promise<void>;
}

// Mouse API
abstract class Mouse {
  abstract click(x: number, y: number, options?: Readonly<MouseClickOptions>): Promise<void>;
  abstract move(x: number, y: number, options?: Readonly<MouseMoveOptions>): Promise<void>;
  abstract down(options?: Readonly<MouseOptions>): Promise<void>;
  abstract up(options?: Readonly<MouseOptions>): Promise<void>;
}

Import

// All accessed through a Page instance
const page = await browser.newPage();
const locator = page.locator('button#submit');  // Locator API
page.keyboard;  // Keyboard instance
page.mouse;     // Mouse instance

I/O Contract

Inputs

Name	Type	Required	Description
selector	string	Yes (Locator)	CSS selector, text selector, or other supported selector syntax
text	string	Yes (Keyboard.type)	Text to type character by character
key	KeyInput	Yes (Keyboard.press)	Key name (e.g., 'Enter', 'Tab', 'ArrowDown')
x, y	number	Yes (Mouse.click/move)	Screen coordinates
options.delay	number	No	Delay between keystrokes or mouse events in ms

Outputs

Name	Type	Description
Locator actions	Promise<void>	Resolves when the interaction is complete
Keyboard actions	Promise<void>	Resolves when key events are dispatched
Mouse actions	Promise<void>	Resolves when mouse events are dispatched

Usage Examples

Locator Click

// Auto-waits for element to be visible and clickable
await page.locator('button#submit').click();

Fill a Form Field

await page.locator('input[name="search"]').fill('puppeteer');

Keyboard Typing

await page.keyboard.type('Hello World', {delay: 100});
await page.keyboard.press('Enter');

Mouse Click At Coordinates

await page.mouse.click(100, 200);
await page.mouse.click(100, 200, {button: 'right'}); // Right-click

Search Example (From Puppeteer Examples)

const puppeteer = require('puppeteer');

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://developer.chrome.com/');
await page.locator('.devsite-search-field').click();
await page.keyboard.type('Headless Chrome');
await page.keyboard.press('Enter');
await page.waitForSelector('.gsc-result');
await browser.close();

Related Pages

Implements Principle

• Principle:Puppeteer_Puppeteer_Element_Interaction

Requires Environment

• Environment:Puppeteer_Puppeteer_Node_18_Runtime