Skip to main content
Frame represents an iframe on a page. Every page has a main frame and can have multiple child frames.

​
Inheritance

Extends: ChannelOwner

​
Methods

​
page

Returns the parent page. 
page(): Page
Returns: Page - Parent page

​
name

Returns frame name. 
name(): string
Returns: string - Frame name attribute

​
url

Returns frame URL. 
url(): string
Returns: string - Frame URL

​
parentFrame

Returns parent frame. 
parentFrame(): Frame | null
Returns: Frame | null - Parent frame or null for main frame

​
childFrames

Returns child frames. 
childFrames(): Frame[]
Returns: Frame[] - Array of child frames

​
isDetached

Checks if frame is detached. 
isDetached(): boolean
Returns: boolean - True if detached

​
frameElement

Returns the frame element handle. 
frameElement(): Promise<ElementHandle>
Returns: Promise<ElementHandle> - Frame element (iframe)

​
goto

Navigates to a URL. 
goto(url: string, options?: GotoOptions): Promise<Response | null>
​
url
string
required
URL to navigate to
​
options
GotoOptions
Navigation options
  • timeout (number): Maximum time in milliseconds
  • waitUntil (‘load’ | ‘domcontentloaded’ | ‘networkidle’ | ‘commit’): When to consider navigation succeeded
  • referer (string): Referer header
Returns: Promise<Response | null> - Response

​
waitForNavigation

Waits for navigation. 
waitForNavigation(options?: WaitForNavigationOptions): Promise<Response | null>
​
options
WaitForNavigationOptions
Wait options
  • url (string | RegExp): URL pattern to wait for
  • waitUntil (string): Wait condition
  • timeout (number): Maximum time
Returns: Promise<Response | null> - Response

​
waitForLoadState

Waits for load state. 
waitForLoadState(state?: 'load' | 'domcontentloaded' | 'networkidle', options?: TimeoutOptions): Promise<void>
​
state
string
Load state to wait for (default: ‘load’)
​
options
TimeoutOptions
Timeout options
Returns: Promise<void>

​
waitForURL

Waits for URL to match pattern. 
waitForURL(url: string | RegExp, options?: WaitForURLOptions): Promise<void>
​
url
string | RegExp
required
URL pattern to wait for
​
options
WaitForURLOptions
Wait options
Returns: Promise<void>

​
Selector Methods

​
$

Finds an element. 
$(selector: string, options?: { strict?: boolean }): Promise<ElementHandle | null>
​
selector
string
required
Selector to query
​
options
object
  • strict (boolean): Throw if multiple elements match
Returns: Promise<ElementHandle | null> - Element handle or null

​
$$

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

​
waitForSelector

Waits for element to appear. 
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 to wait for
  • timeout (number): Maximum time
  • strict (boolean): Throw if multiple elements match
Returns: Promise<ElementHandle | null> - Element handle or null

​
locator

Creates a locator. 
locator(selector: string, options?: LocatorOptions): Locator
​
selector
string
required
Selector to locate
​
options
LocatorOptions
Locator options
Returns: Locator - Locator instance

​
getByRole

Creates a locator by ARIA role. 
getByRole(role: string, options?: ByRoleOptions): Locator

​
getByText

Creates a locator by text. 
getByText(text: string | RegExp, options?: { exact?: boolean }): Locator

​
getByLabel

Creates a locator by label. 
getByLabel(text: string | RegExp, options?: { exact?: boolean }): Locator

​
getByPlaceholder

Creates a locator by placeholder. 
getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): Locator

​
getByAltText

Creates a locator by alt text. 
getByAltText(text: string | RegExp, options?: { exact?: boolean }): Locator

​
getByTitle

Creates a locator by title. 
getByTitle(text: string | RegExp, options?: { exact?: boolean }): Locator

​
getByTestId

Creates a locator by test ID. 
getByTestId(testId: string | RegExp): Locator

​
frameLocator

Creates a frame locator. 
frameLocator(selector: string): FrameLocator
​
selector
string
required
Frame selector
Returns: FrameLocator - Frame locator instance

​
Action Methods

​
click

Clicks an element. 
click(selector: string, options?: ClickOptions): Promise<void>

​
dblclick

Double clicks an element. 
dblclick(selector: string, options?: DblClickOptions): Promise<void>

​
fill

Fills an input. 
fill(selector: string, value: string, options?: FillOptions): Promise<void>

​
type

Types text. 
type(selector: string, text: string, options?: TypeOptions): Promise<void>

​
press

Presses a key. 
press(selector: string, key: string, options?: PressOptions): Promise<void>

​
check

Checks a checkbox. 
check(selector: string, options?: CheckOptions): Promise<void>

​
uncheck

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

​
setChecked

Sets checkbox state. 
setChecked(selector: string, checked: boolean, options?: CheckOptions): Promise<void>

​
selectOption

Selects options. 
selectOption(selector: string, values: string | string[] | SelectOption | SelectOption[], options?: SelectOptionOptions): Promise<string[]>

​
hover

Hovers over element. 
hover(selector: string, options?: HoverOptions): Promise<void>

​
tap

Taps an element. 
tap(selector: string, options?: TapOptions): Promise<void>

​
dragAndDrop

Drags and drops. 
dragAndDrop(source: string, target: string, options?: DragAndDropOptions): Promise<void>

​
focus

Focuses an element. 
focus(selector: string, options?: TimeoutOptions): Promise<void>

​
setInputFiles

Sets input files. 
setInputFiles(selector: string, files: string | string[] | FilePayload | FilePayload[], options?: SetInputFilesOptions): Promise<void>

​
dispatchEvent

Dispatches a DOM event. 
dispatchEvent(selector: string, type: string, eventInit?: any, options?: TimeoutOptions): Promise<void>

​
Content Methods

​
content

Returns HTML content. 
content(): Promise<string>
Returns: Promise<string> - Full HTML content

​
setContent

Sets HTML content. 
setContent(html: string, options?: SetContentOptions): Promise<void>
​
html
string
required
HTML content to set
​
options
SetContentOptions
Set content options
Returns: Promise<void>

​
title

Returns page title. 
title(): Promise<string>
Returns: Promise<string> - Page title

​
textContent

Returns element’s text content. 
textContent(selector: string, options?: TimeoutOptions): Promise<string | null>

​
innerText

Returns element’s inner text. 
innerText(selector: string, options?: TimeoutOptions): Promise<string>

​
innerHTML

Returns element’s inner HTML. 
innerHTML(selector: string, options?: TimeoutOptions): Promise<string>

​
getAttribute

Returns attribute value. 
getAttribute(selector: string, name: string, options?: TimeoutOptions): Promise<string | null>

​
inputValue

Returns input value. 
inputValue(selector: string, options?: TimeoutOptions): Promise<string>

​
State Methods

​
isVisible

Checks if visible. 
isVisible(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isHidden

Checks if hidden. 
isHidden(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isEnabled

Checks if enabled. 
isEnabled(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isDisabled

Checks if disabled. 
isDisabled(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isChecked

Checks if checked. 
isChecked(selector: string, options?: TimeoutOptions): Promise<boolean>

​
isEditable

Checks if editable. 
isEditable(selector: string, options?: TimeoutOptions): Promise<boolean>

​
Evaluation Methods

​
evaluate

Evaluates JavaScript. 
evaluate<R, Arg>(pageFunction: Function | string, arg?: Arg): Promise<R>
​
pageFunction
Function | string
required
Function to evaluate
​
arg
any
Argument to pass
Returns: Promise<R> - Evaluation result

​
evaluateHandle

Evaluates and returns JSHandle. 
evaluateHandle<R, Arg>(pageFunction: Function | string, arg?: Arg): Promise<JSHandle<R>>

​
$eval

Evaluates on an element. 
$eval<R, Arg>(selector: string, pageFunction: Function, arg?: Arg): Promise<R>

​
$$eval

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

​
Script Methods

​
addScriptTag

Adds a script tag. 
addScriptTag(options: { url?: string, path?: string, content?: string, type?: string }): Promise<ElementHandle>
​
options
object
required
Script options
  • url (string): Script URL
  • path (string): Path to script file
  • content (string): Script content
  • type (string): Script type
Returns: Promise<ElementHandle> - Script element handle

​
addStyleTag

Adds a style tag. 
addStyleTag(options: { url?: string, path?: string, content?: string }): Promise<ElementHandle>
​
options
object
required
Style options
  • url (string): Stylesheet URL
  • path (string): Path to stylesheet file
  • content (string): CSS content
Returns: Promise<ElementHandle> - Style element handle

​
Wait Methods

​
waitForTimeout

Waits for timeout. 
waitForTimeout(timeout: number): Promise<void>
​
timeout
number
required
Timeout in milliseconds
Returns: Promise<void>

​
waitForFunction

Waits for function to return truthy value. 
waitForFunction<R, Arg>(pageFunction: Function | string, arg?: Arg, options?: WaitForFunctionOptions): Promise<JSHandle<R>>
​
pageFunction
Function | string
required
Function to evaluate
​
arg
any
Argument to pass
​
options
WaitForFunctionOptions
Wait options
  • timeout (number): Maximum time
  • polling (number | ‘raf’): Polling interval
Returns: Promise<JSHandle<R>> - JS handle

​
Usage Examples

​
Working with Frames

import { chromium } from 'playwright';

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

const mainFrame = page.mainFrame();
console.log('Main frame URL:', mainFrame.url());

const frames = page.frames();
console.log('Total frames:', frames.length);

for (const frame of frames) {
  console.log('Frame:', frame.name(), frame.url());
}

await browser.close();

​
Interacting with Frame Content

const frame = page.frame({ name: 'my-iframe' });
if (frame) {
  await frame.fill('#input', 'Hello from iframe');
  await frame.click('button#submit');
  
  const content = await frame.content();
  console.log(content);
}

​
Frame Locators

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

const frameLocator = page.frameLocator('iframe#my-frame');
const button = frameLocator.getByRole('button', { name: 'Click me' });
await button.click();

Build docs developers (and LLMs) love

Get started for freeTalk to us