Implementation:Puppeteer Puppeteer QueryHandler

Property	Value
sources	packages/puppeteer-core/src/common/QueryHandler.ts
domains	Query Handling, Element Selection, Core Infrastructure
last_updated	2026-02-12 00:00 GMT

Overview

Description

QueryHandler is the internal base class for all element query handlers in Puppeteer. It defines the contract and default implementations for querying DOM elements, and serves as the foundation that specialized handlers like ARIAQueryHandler and custom query handlers extend.

The module exports several key types and constructs:

• QuerySelectorAll -- A function type for selecting multiple nodes given a selector.
• QuerySelector -- A function type for selecting a single node given a selector.
• PollingOptions -- An enum with values 'raf' (requestAnimationFrame-based polling) and 'mutation' (MutationObserver-based polling).

The QueryHandler class provides:

• querySelectorAll / querySelector -- Static properties that subclasses can override. These are the browser-side selector functions that run inside the page context.
• _querySelector / _querySelectorAll -- Computed getters that provide default implementations. If only one of querySelector/querySelectorAll is defined, the other is derived automatically using function interpolation.
• queryAll -- An async generator that evaluates _querySelectorAll in the browser and transposes the result into Puppeteer-side handles using transposeIterableHandle.
• queryOne -- Evaluates _querySelector in the browser and returns a single element handle or null.
• waitFor -- A sophisticated method that waits for an element matching the selector to appear (with optional visibility/hidden checks). It works in the isolated realm, supports timeout and abort signals, and migrates the result handle to the main realm.

Usage

This class is used internally as the base for all query operations in Puppeteer. Methods like page.$, page.$$, and page.waitForSelector ultimately delegate to QueryHandler methods (or subclass overrides thereof).

Code Reference

Source Location

packages/puppeteer-core/src/common/QueryHandler.ts

Signature

export type QuerySelectorAll = (
  node: Node,
  selector: string,
  PuppeteerUtil: PuppeteerInjectedUtil,
) => AwaitableIterable<Node>;

export type QuerySelector = (
  node: Node,
  selector: string,
  PuppeteerUtil: PuppeteerInjectedUtil,
) => Awaitable<Node | null>;

export const enum PollingOptions {
  RAF = 'raf',
  MUTATION = 'mutation',
}

export class QueryHandler {
  static querySelectorAll?: QuerySelectorAll;
  static querySelector?: QuerySelector;

  static get _querySelector(): QuerySelector;
  static get _querySelectorAll(): QuerySelectorAll;

  static async *queryAll(
    element: ElementHandle<Node>,
    selector: string,
  ): AwaitableIterable<ElementHandle<Node>>;

  static async queryOne(
    element: ElementHandle<Node>,
    selector: string,
  ): Promise<ElementHandle<Node> | null>;

  static async waitFor(
    elementOrFrame: ElementHandle<Node> | Frame,
    selector: string,
    options: WaitForSelectorOptions & { polling?: PollingOptions },
  ): Promise<ElementHandle<Node> | null>;
}

Import

import {QueryHandler, type QuerySelector, type QuerySelectorAll, PollingOptions} from './QueryHandler.js';

I/O Contract

Method	Parameters	Return Type	Description
queryAll	element: ElementHandle<Node>, selector: string	AwaitableIterable<ElementHandle<Node>>	Yields handles for all matching elements
queryOne	element: ElementHandle<Node>, selector: string	null>	Returns a handle to the first matching element or null
waitFor	elementOrFrame, selector, options	null>	Waits for a matching element to appear with configurable polling, visibility, timeout, and abort signal

WaitFor Option	Type	Description
visible	boolean	Wait for element to be visible (default: false)
hidden	boolean	Wait for element to be hidden (default: false)
timeout	number	Maximum time to wait in milliseconds
signal	AbortSignal	An abort signal to cancel the wait
polling	PollingOptions	Polling strategy: 'raf' or 'mutation'

Usage Examples

// Internal usage - QueryHandler is used as the base class for selectors

// Subclassing QueryHandler for a custom handler
import {QueryHandler, type QuerySelector} from './QueryHandler.js';

class MyCustomHandler extends QueryHandler {
  static override querySelector: QuerySelector = (node, selector, PuppeteerUtil) => {
    return node.querySelector(`[data-custom="${selector}"]`);
  };
}

// The waitFor method is used internally by page.waitForSelector
// It uses the isolated realm for evaluation and transfers the handle to the main realm
const element = await QueryHandler.waitFor(frame, 'div.target', {
  visible: true,
  timeout: 5000,
  polling: PollingOptions.RAF,
});

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime