Frame

API reference for the Frame class - interact with page frames

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)

Navigation Methods

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

Related Classes

• Page - Parent page
• Locator - Element locators
• ElementHandle - Element handles
• FrameLocator - Frame locators