> For the complete documentation index, see [llms.txt](https://docs.gpmautomate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gpmautomate.com/automate-en/action-guides/switch/switch-to-frame.md).

# Switch to frame

In the structure of web design, Iframe (Inline Frame) is understood as an independent browser window embedded within another web page.

When an element (such as a button, input field) is inside the `<iframe>` tag, the GPM Automate system will not be able to find its XPath if you are still in the main web page space. You must use the Switch to frame action to "enter" that Iframe in order to interact with it. After finishing the interaction, you must use Switch to default to "exit" back to the main interface.

#### 1. Action to switch into Iframe (Switch to frame)

* Purpose: Transfer control of the script into a specified Iframe window.
* Configuration parameters:
  * XPath: The XPath path directly to the target `<iframe>` tag on the web page.

#### 2. Action to return to the main interface (Switch to default)

* Purpose: Release control from the current Iframe to return to the original web page structure. This action has no configuration parameters.

#### Real-world example: Click the "Continue with Google" button on Pinterest (Attached image)

Based on the image below, the Continue with Google button is not actually located directly on the Pinterest page, but is contained within a secure Iframe window embedded by Google (The red arrow at the top right of the source code points directly to the `<iframe src="https://accounts.google.com...">` tag).

If you only use the *Mouse click* command directly on the *Continue with Google* button (`//span[text()="Continue with Google"]`), the script will immediately report an element not found error. The standard processing procedure must be configured as follows:

* Step 1 (Enter Iframe): Drag the Switch to frame action into the script.
  * *XPath*: Enter the XPath of the iframe tag as you found: `//iframe[contains(@src,'accounts.google.com')]`
* Step 2 (Click the button): Drag the Mouse click action into the flow.
  * *Click type*: Click based on XPath.
  * *XPath*: Enter the XPath of the button inside the iframe: `//span[contains(text(),"Continue with Google")]`
* Step 3 (Exit): Drag the Switch to default action right after to bring the browser back to the main space of the Pinterest page, ready for the form filling steps (Email, Password) outside if needed.

<figure><img src="/files/by6Kfrcm4KLzAw93U7ub" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/JJ1bRjDGxSZYxB2DZzXo" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/m9F6n2lDWDPsc7FExy9i" alt=""><figcaption></figcaption></figure>

To understand Iframe (Frame) in web programming in the simplest and most imaginative way, think of a wall and the picture frames hanging on it.

#### 1. Metaphorical image of a Picture Frame

* The main wall: This is the entire web page you are accessing (for example: the page `pinterest.com`). On this wall, there is its own paint color, a door, and furniture around.
* The picture frame on the wall (Iframe): Is a frame that is either cut out or hung on that wall. The special thing is that inside this picture frame is not a static image, but a piece of land owned by someone else entirely (for example: a corner of the office of `accounts.google.com`).

#### 2. The nature of Iframe operation on a website

When a website inserts an Iframe, they are opening a "small window" to allow another website to display its content right on their page:

* Independent content: The owner of the wall (Pinterest) only rents out the space for the picture frame, and has no right to intervene in what is inside that frame, how it operates. Everything inside the frame is managed and secured entirely by the frame owner (Google).
* Viewer (Automation Script): When you stand outside the room, you can see both the wall and the picture frame. But if you want to take a brush to paint on the picture, you cannot just stand far away and swipe on the wall. You must step into the range of the picture frame (`Switch to frame`), then you can touch the details inside it (like the *Continue with Google* button).

#### 3. Why is it mandatory to "Enter" and "Exit" during Automation?

Due to the security nature of the browser, the world outside the wall and the world inside the picture frame are separated by an invisible glass:

* If you do not "Enter" (`Switch to frame`): The automation tool will stand outside the wall and confusedly ask: *"Hey, I clearly see the Google login button on the screen, but why can't I find its XPath?"* -> Because the robot is scanning the code of the wall, not looking through the glass of the picture frame.
* If you do not "Exit" (`Switch to default`): After you click the button in the picture frame, you want to go back to click the "Register" button at the bottom corner of the Pinterest page. If you do not exit, the robot will still be wandering around looking for that button inside Google's land, leading to a command not found error.

In summary, Iframe is like a mini website embedded within a larger website, creating a distinct spatial boundary that the automation script must clearly enter/exit to work.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.gpmautomate.com/automate-en/action-guides/switch/switch-to-frame.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.