Call await frame.frameElement() to get the DOM element that hosts a Puppeteer Frame. The returned value is an ElementHandle; use it to inspect iframe attributes or interact with the iframe element. To query the embedded document, use the Frame itself instead.
Get the iframe element from a Frame
When you already have a child Frame, call its frameElement() method:
As an Amazon Associate I earn from qualifying purchases.
const iframeElement = await frame.frameElement();The result is an ElementHandle for the element in the parent document that hosts that frame. For example, read the iframe’s name attribute with evaluate:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →const name = await iframeElement.evaluate(el => el.getAttribute('name'));Puppeteer’s Frame API documents this method and demonstrates reading the host element’s name: Frame.frameElement().
#1 Best Overall
Find a frame by its iframe name
Use page.frames() to get the page’s current frames, then inspect each frame’s host element. Once you find the matching host, use the Frame to query the embedded document:
const frames = page.frames();
let targetFrame = null;
for (const frame of frames) {
const iframeElement = await frame.frameElement();
const name = await iframeElement.evaluate(el => el.getAttribute('name'));
if (name === 'myframe') {
targetFrame = frame;
break;
}
}
if (targetFrame) {
const text = await targetFrame.$eval('.selector', element => element.textContent);
console.log(text);
} else {
console.error('Frame with name "myframe" not found.');
}This searches by the iframe’s name attribute, not by the embedded page’s content. If your page may not have loaded its frames yet, wait for the relevant page state before enumerating them.
Frame versus iframe ElementHandle
These objects point to different parts of the page:
Free tools Windows power users keep installed
One-click scans. No signup required.
Framerepresents the embedded browsing context. Use frame methods such asframe.$()orframe.$eval()to query elements inside its document. See the Frame API.frame.frameElement()moves from a childFrameto the outer DOM element that hosts it.iframeElement.contentFrame()moves in the opposite direction, from the iframe’s element handle to its associatedFrame. The API reference documents the specialized iframe-element signature as returningPromise<Frame>: ElementHandle.contentFrame().
For example, start with an iframe element and retrieve its frame like this:
Rank #3
const iframeElement = await page.$('iframe#myframe');
if (iframeElement) {
const frame = await iframeElement.contentFrame();
// Use frame methods to query the embedded document.
}The null check handles the case where the selector matches no element. If the handle is not an iframe associated with a frame, do not assume it will produce a usable frame.
Know which frames have a host element
A page exposes its main frame through page.mainFrame() and child frames through the frame tree, including Frame.childFrames(). The main frame has no hosting iframe element in the normal parent-child sense: Puppeteer documents that the main frame and detached frames have no parent frame. The host-element operation is therefore intended for child frames. See the Frame API reference.
Handle navigation and detachment
A frame or element handle is tied to a live page context. Puppeteer documents that element handles are automatically disposed when their associated frame navigates away or their parent context is destroyed. If navigation, removal, or frame detachment can occur while your code is running, avoid keeping the handle for later use; reacquire the frame and element after the page reaches the state you need. The ElementHandle API describes handle lifetime.
The official API pages surfaced for this method identify the Frame reference as Puppeteer 25.12.0 and the ElementHandle.contentFrame() reference as 25.10.0. These are the versions shown on those pages, not evidence of when either method was first introduced.
Or skip the browser setup
If your goal is to capture a page rather than inspect its iframe DOM, ScreenshotNeo can return a screenshot or PDF with one GET request. Its cookie and consent handling removes supported consent banners, newsletter popups, and chat widgets before capture; failed loads, bot checks, blank pages, and cache hits are not billed. An MCP server lets AI agents use its screenshot tools. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
cURL example:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo is a website screenshot API and MCP server by Yorker Media: ScreenshotNeo. Sign up for 1,000 free screenshots a month, with no card required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
