Frame class

Represents a DOM frame.

To understand frames, you can think of frames as <iframe> elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not affect frames inside the ambient frame the JavaScript executes in.

Signature

export declare abstract class Frame extends EventEmitter<FrameEvents>

Extends: EventEmitter<FrameEvents>

Remarks

Frame lifecycles are controlled by three events that are all dispatched on the parent page:

• PageEvent.FrameAttached - PageEvent.FrameNavigated - PageEvent.FrameDetached

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Frame class.

Example 1

At any point in time, pages expose their current frame tree via the Page.mainFrame() and Frame.childFrames() methods.

Example 2

An example of dumping frame tree:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://www.google.com/chrome/browser/canary.html');
dumpFrameTree(page.mainFrame(), '');
await browser.close();

function dumpFrameTree(frame, indent) {
  console.log(indent + frame.url());
  for (const child of frame.childFrames()) {
    dumpFrameTree(child, indent + '  ');
  }
}

Example 3

An example of getting text from an iframe element:

const frames = page.frames();
let frame = null;
for (const currentFrame of frames) {
  const frameElement = await currentFrame.frameElement();
  const name = await frameElement.evaluate(el => el.getAttribute('name'));
  if (name === 'myframe') {
    frame = currentFrame;
    break;
  }
}
if (frame) {
  const text = await frame.$eval('.selector', element => element.textContent);
  console.log(text);
} else {
  console.error('Frame with name "myframe" not found.');
}

Properties

Property

Modifiers

Type

Description

<span id="detached">detached</span>

readonly

boolean

Methods

Method

Modifiers

Description

<span id="_">$(selector)</span>

Queries the frame for an element matching the given selector.

<span id="__">$$(selector, options)</span>

Queries the frame for all elements matching the given selector.

<span id="__eval">$$eval(selector, pageFunction, args)</span>

Runs the given function on an array of elements matching the given selector in the frame.

If the given function returns a promise, then this method will wait till the promise resolves.

<span id="_eval">$eval(selector, pageFunction, args)</span>

Runs the given function on the first element matching the given selector in the frame.

If the given function returns a promise, then this method will wait till the promise resolves.

<span id="addscripttag">addScriptTag(options)</span>

Adds a <script> tag into the page with the desired url or content.

<span id="addstyletag">addStyleTag(options)</span>

Adds a HTMLStyleElement into the frame with the desired URL

<span id="addstyletag">addStyleTag(options)</span>

Adds a HTMLLinkElement into the frame with the desired URL

<span id="childframes">childFrames()</span>

An array of child frames.

<span id="click">click(selector, options)</span>

Clicks the first element found that matches selector.

Remarks:

If click() triggers a navigation event and there's a separate page.waitForNavigation() promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:

const [response] = await Promise.all([
  page.waitForNavigation(waitOptions),
  frame.click(selector, clickOptions),
]);

<span id="content">content()</span>

The full HTML contents of the frame, including the DOCTYPE.

<span id="evaluate">evaluate(pageFunction, args)</span>

Behaves identically to Page.evaluate() except it's run within the context of this frame.

See Page.evaluate() for details.

<span id="evaluatehandle">evaluateHandle(pageFunction, args)</span>

Behaves identically to Page.evaluateHandle() except it's run within the context of this frame.

See Page.evaluateHandle() for details.

<span id="focus">focus(selector)</span>

Focuses the first element that matches the selector.

<span id="frameelement">frameElement()</span>

<span id="goto">goto(url, options)</span>

Navigates the frame or page to the given url.

Remarks:

Navigation to about:blank or navigation to the same URL with a different hash will succeed and return null.

:::warning

Headless shell mode doesn't support navigation to a PDF document. See the upstream issue.

:::

In headless shell, this method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling HTTPResponse.status().

<span id="hover">hover(selector)</span>

Hovers the pointer over the center of the first element that matches the selector.

<span id="isdetached">isDetached()</span>

deprecated

Istrue if the frame has been detached. Otherwise, false.

Deprecated:

Use the detached getter.

<span id="locator">locator(selector)</span>

Creates a locator for the provided selector. See Locator for details and supported actions.

<span id="locator">locator(func)</span>

Creates a locator for the provided function. See Locator for details and supported actions.

<span id="name">name()</span>

deprecated

The frame's name attribute as specified in the tag.

Deprecated:

Use

const element = await frame.frameElement();
const nameOrId = await element.evaluate(frame => frame.name ?? frame.id);

Remarks:

This value is calculated once when the frame is created, and will not update if the attribute is changed later.

<span id="page">page()</span>

The page associated with the frame.

<span id="parentframe">parentFrame()</span>

The parent frame, if any. Detached and main frames return null.

<span id="select">select(selector, values)</span>

Selects a set of value on the first <select> element that matches the selector.

<span id="setcontent">setContent(html, options)</span>

Set the content of the frame.

<span id="tap">tap(selector)</span>

Taps the first element that matches the selector.

<span id="title">title()</span>

The frame's title.

<span id="type">type(selector, text, options)</span>

Sends a keydown, keypress/input, and keyup event for each character in the text.

Remarks:

To press a special key, like Control or ArrowDown, use Keyboard.press().

<span id="url">url()</span>

The frame's URL.

<span id="waitforfunction">waitForFunction(pageFunction, options, args)</span>

<span id="waitfornavigation">waitForNavigation(options)</span>

Waits for the frame to navigate. It is useful for when you run code which will indirectly cause the frame to navigate.

Usage of the History API to change the URL is considered a navigation.

<span id="waitforselector">waitForSelector(selector, options)</span>

Waits for an element matching the given selector to appear in the frame.

This method works across navigations.