Implementation:Microsoft Playwright Client JSHandle

Knowledge Sources	Microsoft_Playwright
Domains	Browser Automation, JavaScript Evaluation
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for representing handles to JavaScript objects in the browser page context provided by the Playwright library.

Description

The JSHandle class extends ChannelOwner and implements api.JSHandle. It represents a reference to a JavaScript object in the browser's execution context. The handle maintains a _preview string that is dynamically updated via the 'previewUpdated' channel event. Key methods include:

• evaluate() and evaluateHandle(): Execute a function in the browser context with this handle as the first argument, returning either a deserialized value or a new JSHandle.
• getProperty() and getProperties(): Access individual or all properties of the referenced object.
• jsonValue(): Serialize the referenced object to a JSON-compatible value.
• asElement(): Attempt to cast to an ElementHandle (returns null for non-element handles).
• dispose(): Release the handle, freeing server-side resources. Silently succeeds if the target is already closed.

The module also exports utility functions: serializeArgument() for converting JavaScript values and JSHandle instances into protocol-compatible serialized arguments, parseResult() for deserializing protocol values back to JavaScript, and assertMaxArguments() for parameter count validation.

Usage

Use JSHandle when you need to maintain references to browser-side JavaScript objects across multiple evaluations, pass objects between evaluations, or inspect object properties. Obtain instances from page.evaluateHandle(), jsHandle.evaluateHandle(), or jsHandle.getProperty().

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/client/jsHandle.ts

Signature

export class JSHandle<T = any> extends ChannelOwner<channels.JSHandleChannel> implements api.JSHandle {
  static from(handle: channels.JSHandleChannel): JSHandle;

  constructor(parent: ChannelOwner, type: string, guid: string, initializer: channels.JSHandleInitializer);

  async evaluate<R, Arg>(pageFunction: PageFunctionOn<T, Arg, R>, arg?: Arg): Promise<R>;
  async evaluateHandle<R, Arg>(pageFunction: PageFunctionOn<T, Arg, R>, arg?: Arg): Promise<SmartHandle<R>>;
  async getProperty(propertyName: string): Promise<JSHandle>;
  async getProperties(): Promise<Map<string, JSHandle>>;
  async jsonValue(): Promise<T>;
  asElement(): ElementHandle | null;
  async dispose(): Promise<void>;
  toString(): string;
}

export function serializeArgument(arg: any): channels.SerializedArgument;
export function parseResult(value: channels.SerializedValue): any;
export function assertMaxArguments(count: number, max: number): asserts count;

Import

import { JSHandle, serializeArgument, parseResult } from 'playwright-core/src/client/jsHandle';

I/O Contract

Inputs

Name	Type	Required	Description
pageFunction	string	Yes	The function or expression to evaluate with this handle
arg	any	No	Additional argument to pass to the evaluation function
propertyName	string	Yes	The property name to retrieve from the referenced object

Outputs

Name	Type	Description
evaluate()	Promise<R>	The deserialized return value of the evaluated function
evaluateHandle()	Promise<SmartHandle<R>>	A new JSHandle referencing the return value
getProperty()	Promise<JSHandle>	A JSHandle to the specified property
getProperties()	Promise<Map<string, JSHandle>>	Map of all enumerable property names to their JSHandle values
jsonValue()	Promise<T>	The JSON-serializable value of the referenced object
toString()	string	A human-readable preview string of the handle

Usage Examples

// Get a handle to an object
const handle = await page.evaluateHandle(() => ({ name: 'test', value: 42 }));

// Access properties
const nameHandle = await handle.getProperty('name');
console.log(await nameHandle.jsonValue()); // 'test'

// Get all properties
const properties = await handle.getProperties();
for (const [key, value] of properties) {
  console.log(`${key}: ${await value.jsonValue()}`);
}

// Evaluate with the handle
const result = await handle.evaluate((obj) => obj.name + ': ' + obj.value);
console.log(result); // 'test: 42'

// Clean up
await handle.dispose();

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment