ElementHandle - Playwright

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>

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>

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>

string

required

Value to fill

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>

string

required

Text to type

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>

string

required

Key to press (e.g., ‘Enter’, ‘ArrowDown’, ‘Control+A’)

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>

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>

boolean

required

Whether to check or uncheck

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[]>

required

Values to select

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>

string | string[] | FilePayload | FilePayload[]

required

File paths or file payloads to upload

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>

string

required

Event type (e.g., ‘click’, ‘submit’)

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>

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>

string

required

Selector to query

Returns: Promise<ElementHandle | null> - Element handle or null

$$

Finds all descendant elements.

$$(selector: string): Promise<ElementHandle[]>

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>

string

required

Selector to query

Function

required

Function to evaluate

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>

string

required

Selector to wait for

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>

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>

ScrollOptions

Scroll options

timeout (number): Maximum time

Returns: Promise<void>

selectText

Selects text in the element.

selectText(options?: TimeoutOptions): Promise<void>

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>

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

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('john@example.com', { 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

Memory Management: Always dispose of ElementHandles when done to prevent memory leaks:

const element = await page.$('button');
await element?.click();
await element?.dispose();

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();

Stale References: ElementHandles can become stale if the DOM changes. Locators automatically re-query.
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

​Inheritance

​Constructor

​Frame Methods

​ownerFrame

​contentFrame

​Action Methods

​click

​dblclick

​tap

​hover

​fill

​type

​press

​check

​uncheck

​setChecked

​selectOption

​focus

​setInputFiles

​dispatchEvent

​Content Methods

​textContent

​innerText

​innerHTML

​getAttribute

​inputValue

​State Methods

​isVisible

​isHidden

​isEnabled

​isDisabled

​isChecked

​isEditable

​Selector Methods

​$

​$$

​$eval

​$$eval

​waitForSelector

​Utility Methods

​boundingBox

​screenshot

​scrollIntoViewIfNeeded

​selectText

​waitForElementState

​Usage Examples

​Basic ElementHandle Usage

​Querying Descendants

​Getting Element Properties

​Form Interactions

​Taking Element Screenshots

​Working with Frames

​Waiting for Element State

​Important Notes

​Related Classes

Inheritance

Constructor

Frame Methods

ownerFrame

contentFrame

Action Methods

click

dblclick

tap

hover

fill

type

press

check

uncheck

setChecked

selectOption

focus

setInputFiles

dispatchEvent

Content Methods

textContent

innerText

innerHTML

getAttribute

inputValue

State Methods

isVisible

isHidden

isEnabled

isDisabled

isChecked

isEditable

Selector Methods

$

$$

$eval

$$eval

waitForSelector

Utility Methods

boundingBox

screenshot

scrollIntoViewIfNeeded

selectText

waitForElementState

Usage Examples

Basic ElementHandle Usage

Querying Descendants

Getting Element Properties

Form Interactions

Taking Element Screenshots

Working with Frames

Waiting for Element State

Important Notes

Related Classes