Skip to main content
ElementHandle represents an in-page DOM element. ElementHandles are discouraged in favor of Locators, but they are useful when you need to retain a reference to a specific element.

​
Inheritance

Extends: JSHandle<Node>

​
Constructor

ElementHandles are typically created through page methods like page.$() or frame.$().

​
Frame Methods

​
ownerFrame

Returns the frame containing this element. 
ownerFrame(): Promise<Frame | null>
Returns: Promise<Frame | null> - Owner frame or null

​
contentFrame

Returns the content frame for iframe elements. 
contentFrame(): Promise<Frame | null>
Returns: Promise<Frame | null> - Content frame or null

​
Action Methods

​
click

Clicks the element. 
click(options?: ClickOptions): Promise<void>
​
options
ClickOptions
Click options
  • button (‘left’ | ‘right’ | ‘middle’): Mouse button
  • clickCount (number): Number of clicks
  • delay (number): Delay between mousedown and mouseup
  • position (object): Click position
  • modifiers (string[]): Modifier keys
  • force (boolean): Force click
  • noWaitAfter (boolean): Don’t wait after click
  • timeout (number): Maximum time
Returns: Promise<void>

​
dblclick

Double clicks the element. 
dblclick(options?: DblClickOptions): Promise<void>

​
tap

Taps the element. 
tap(options?: TapOptions): Promise<void>

​
hover

Hovers over the element. 
hover(options?: HoverOptions): Promise<void>
​
options
HoverOptions
Hover options
  • position (object): Hover position
  • modifiers (string[]): Modifier keys
  • force (boolean): Force hover
  • timeout (number): Maximum time
Returns: Promise<void>

​
fill

Fills an input element. 
fill(value: string, options?: FillOptions): Promise<void>
​
value
string
required
Value to fill
​
options
FillOptions
Fill options
  • force (boolean): Force fill
  • noWaitAfter (boolean): Don’t wait after fill
  • timeout (number): Maximum time
Returns: Promise<void>

​
type

Types text into the element. 
type(text: string, options?: TypeOptions): Promise<void>
​
text
string
required
Text to type
​
options
TypeOptions
Type options
  • delay (number): Delay between key presses in milliseconds
  • noWaitAfter (boolean): Don’t wait after typing
  • timeout (number): Maximum time
Returns: Promise<void>

​
press

Presses a key. 
press(key: string, options?: PressOptions): Promise<void>
​
key
string
required
Key to press (e.g., ‘Enter’, ‘ArrowDown’, ‘Control+A’)
​
options
PressOptions
Press options
  • delay (number): Delay between keydown and keyup
  • noWaitAfter (boolean): Don’t wait after press
  • timeout (number): Maximum time
Returns: Promise<void>

​
check

Checks a checkbox or radio button. 
check(options?: CheckOptions): Promise<void>
​
options
CheckOptions
Check options
  • force (boolean): Force check
  • noWaitAfter (boolean): Don’t wait after check
  • timeout (number): Maximum time
Returns: Promise<void>

​
uncheck

Unchecks a checkbox. 
uncheck(options?: CheckOptions): Promise<void>

​
setChecked

Sets checkbox state. 
setChecked(checked: boolean, options?: CheckOptions): Promise<void>
​
checked
boolean
required
Whether to check or uncheck
​
options
CheckOptions
Check options
Returns: Promise<void>

​
selectOption

Selects options in a <select> element. 
selectOption(values: string | string[] | ElementHandle | ElementHandle[] | SelectOption | SelectOption[], options?: SelectOptionOptions): Promise<string[]>
​
values
string | string[] | ElementHandle | ElementHandle[] | SelectOption | SelectOption[]
required
Values to select
​
options
SelectOptionOptions
Select options
  • force (boolean): Force select
  • noWaitAfter (boolean): Don’t wait after select
  • timeout (number): Maximum time
Returns: Promise<string[]> - Array of selected option values

​
focus

Focuses the element. 
focus(): Promise<void>
Returns: Promise<void>

​
setInputFiles

Sets files for a file input element. 
setInputFiles(files: string | string[] | FilePayload | FilePayload[], options?: SetInputFilesOptions): Promise<void>
​
files
string | string[] | FilePayload | FilePayload[]
required
File paths or file payloads to upload
​
options
SetInputFilesOptions
Upload options
  • noWaitAfter (boolean): Don’t wait after setting files
  • timeout (number): Maximum time
Returns: Promise<void>

​
dispatchEvent

Dispatches a DOM event. 
dispatchEvent(type: string, eventInit?: any): Promise<void>
​
type
string
required
Event type (e.g., ‘click’, ‘submit’)
​
eventInit
any
Event initialization object
Returns: Promise<void>

​
Content Methods

​
textContent

Returns element’s text content. 
textContent(): Promise<string | null>
Returns: Promise<string | null> - Text content or null

​
innerText

Returns element’s inner text. 
innerText(): Promise<string>
Returns: Promise<string> - Inner text

​
innerHTML

Returns element’s inner HTML. 
innerHTML(): Promise<string>
Returns: Promise<string> - Inner HTML

​
getAttribute

Returns attribute value. 
getAttribute(name: string): Promise<string | null>
​
name
string
required
Attribute name
Returns: Promise<string | null> - Attribute value or null

​
inputValue

Returns input value. 
inputValue(): Promise<string>
Returns: Promise<string> - Input value

​
State Methods

​
isVisible

Checks if element is visible. 
isVisible(): Promise<boolean>
Returns: Promise<boolean> - True if visible

​
isHidden

Checks if element is hidden. 
isHidden(): Promise<boolean>
Returns: Promise<boolean> - True if hidden

​
isEnabled

Checks if element is enabled. 
isEnabled(): Promise<boolean>
Returns: Promise<boolean> - True if enabled

​
isDisabled

Checks if element is disabled. 
isDisabled(): Promise<boolean>
Returns: Promise<boolean> - True if disabled

​
isChecked

Checks if checkbox or radio is checked. 
isChecked(): Promise<boolean>
Returns: Promise<boolean> - True if checked

​
isEditable

Checks if element is editable. 
isEditable(): Promise<boolean>
Returns: Promise<boolean> - True if editable

​
Selector Methods

​
$

Finds a descendant element. 
$(selector: string): Promise<ElementHandle | null>
​
selector
string
required
Selector to query
Returns: Promise<ElementHandle | null> - Element handle or null

​
$$

Finds all descendant elements. 
$$(selector: string): Promise<ElementHandle[]>
​
selector
string
required
Selector to query
Returns: Promise<ElementHandle[]> - Array of element handles

​
$eval

Evaluates function on a descendant element. 
$eval<R, Arg>(selector: string, pageFunction: Function, arg?: Arg): Promise<R>
​
selector
string
required
Selector to query
​
pageFunction
Function
required
Function to evaluate
​
arg
any
Argument to pass to function
Returns: Promise<R> - Evaluation result

​
$$eval

Evaluates function on all descendant elements. 
$$eval<R, Arg>(selector: string, pageFunction: Function, arg?: Arg): Promise<R>

​
waitForSelector

Waits for a descendant element. 
waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<ElementHandle | null>
​
selector
string
required
Selector to wait for
​
options
WaitForSelectorOptions
Wait options
  • state (‘attached’ | ‘visible’ | ‘hidden’ | ‘detached’): Element state
  • timeout (number): Maximum time
Returns: Promise<ElementHandle | null> - Element handle or null

​
Utility Methods

​
boundingBox

Returns element’s bounding box. 
boundingBox(): Promise<Rect | null>
Returns: Promise<Rect | null> - Bounding box or null

​
screenshot

Takes a screenshot of the element. 
screenshot(options?: ScreenshotOptions): Promise<Buffer>
​
options
ScreenshotOptions
Screenshot options
  • path (string): File path to save to
  • type (‘png’ | ‘jpeg’): Image type
  • quality (number): JPEG quality (0-100)
  • omitBackground (boolean): Transparent background
  • timeout (number): Maximum time
  • mask (Locator[]): Elements to mask
Returns: Promise<Buffer> - Screenshot buffer

​
scrollIntoViewIfNeeded

Scrolls element into view if needed. 
scrollIntoViewIfNeeded(options?: ScrollOptions): Promise<void>
​
options
ScrollOptions
Scroll options
  • timeout (number): Maximum time
Returns: Promise<void>

​
selectText

Selects text in the element. 
selectText(options?: TimeoutOptions): Promise<void>
​
options
TimeoutOptions
Timeout options
Returns: Promise<void>

​
waitForElementState

Waits for element to reach a specific state. 
waitForElementState(state: 'visible' | 'hidden' | 'stable' | 'enabled' | 'disabled', options?: TimeoutOptions): Promise<void>
​
state
string
required
State to wait for
  • visible: Element is visible
  • hidden: Element is hidden
  • stable: Element is stable (not animating)
  • enabled: Element is enabled
  • disabled: Element is disabled
​
options
TimeoutOptions
Timeout options
Returns: Promise<void>

​
Usage Examples

​
Basic ElementHandle Usage

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

const button = await page.$('button#submit');
if (button) {
  await button.click();
  await button.dispose();
}

await browser.close();

​
Querying Descendants

const form = await page.$('form');
if (form) {
  const inputs = await form.$$('input');
  console.log(`Found ${inputs.length} inputs`);
  
  const submitButton = await form.$('button[type="submit"]');
  await submitButton?.click();
}

​
Getting Element Properties

const element = await page.$('.info');
if (element) {
  const text = await element.textContent();
  const html = await element.innerHTML();
  const id = await element.getAttribute('id');
  const isVisible = await element.isVisible();
  
  console.log({ text, html, id, isVisible });
}

​
Form Interactions

const nameInput = await page.$('#name');
await nameInput?.fill('John Doe');

const emailInput = await page.$('#email');
await emailInput?.type('[email protected]', { delay: 100 });

const checkbox = await page.$('#terms');
await checkbox?.check();

const select = await page.$('select#country');
await select?.selectOption('US');

​
Taking Element Screenshots

const element = await page.$('.chart');
if (element) {
  await element.screenshot({
    path: 'chart.png',
    type: 'png',
  });
  
  const box = await element.boundingBox();
  console.log('Element position:', box);
}

​
Working with Frames

const iframeElement = await page.$('iframe');
if (iframeElement) {
  const frame = await iframeElement.contentFrame();
  if (frame) {
    await frame.fill('#username', 'user');
    await frame.click('button');
  }
}

​
Waiting for Element State

const button = await page.$('button');
if (button) {
  await button.waitForElementState('visible');
  await button.waitForElementState('enabled');
  await button.click();
}

​
Important Notes

  1. Memory Management: Always dispose of ElementHandles when done to prevent memory leaks: 
    const element = await page.$('button');
await element?.click();
await element?.dispose();
  2. Prefer Locators: Locators are recommended over ElementHandles for most use cases: 
    // Prefer this:
await page.locator('button').click();

// Over this:
const button = await page.$('button');
await button?.click();
  3. Stale References: ElementHandles can become stale if the DOM changes. Locators automatically re-query.
  4. Auto-Waiting: Unlike Locators, ElementHandles don’t automatically wait for actionability. Use waitForElementState() when needed.
  • Locator - Modern element selection (recommended)
  • Page - Page methods for querying elements
  • Frame - Frame methods for querying elements
  • JSHandle - Base class for JavaScript object handles

Build docs developers (and LLMs) love

Get started for freeTalk to us