Docs

Appearance

Iframe interaction ​

This page provides a comprehensive guide for interacting with iframes when capturing screenshots using the POST /screenshot endpoint. The API supports a wide range of user interactions and annotations within iframes to enable detailed and flexible screenshot workflows.

Example 1: Capturing an element within an iframe ​

Let's assume you have a simple page with an iframe that contains a p element.

html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>A page with an iframe</title>
</head>
<body>
<iframe srcdoc="
        <!DOCTYPE html>
        <html lang='en'>
        <head>
            <meta charset='UTF-8'>
            <meta name='viewport' content='width=device-width, initial-scale=1.0'>
            <title>Iframe Content</title>
        </head>
        <body> <h3>What is Lorem Ipsum?</h3>
          <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's
         standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a
         type specimen book.
        </p></body></html>"
        width="100%"
        height="200px">
</iframe>
</body>
</html>

To capture a screenshot of that element which is within the iframe, you need to specify the elementFrame parameter with the index of the iframe related to the main page(frame).

Request ​

POST /screenshot

json
{
  "deviceScaleFactor": 1,
  "elementSelector": [
    "p"
  ],
  "elementFrame": [
    0
  ],
  "steps": [
    {
      "type": "navigate",
      "url": "http://localhost:3000/example.html"
    },
    {
      "type": "waitFor",
      "value": "1500"
    }
  ]
}

Example 2: Interacting with the iframe before capturing a screenshot ​

The API allows you to interact with the iframe before capturing a screenshot. You can execute steps within an iframe by specifying the frame parameter with the index of the iframe related to the main page(frame).

Request ​

POST /screenshot

json
{
  "deviceScaleFactor": 1,
  "steps": [
    {
      "type": "navigate",
      "url": "http://localhost:3000/example.html"
    },
    {
      "type": "waitFor",
      "value": "1500"
    },
    {
      "type": "click",
      "selectors": [
        "p"
      ],
      "frame": [
        0
      ]
    }
  ]
}

In the above example, the step click is executed within the iframe. Other steps like change, hover, hideElement etc can also be executed within the iframe. You can view the full list of steps here. etc.

Example 3: Annotating an element within the iframe ​

You can also annotate an element within an iframe by specifying the frame attribute.

Request ​

POST /screenshot

json
{
  "deviceScaleFactor": 1,
  "elementSelector": [
    "body"
  ],
  "elementFrame": [
    0
  ],
  "steps": [
    {
      "type": "navigate",
      "url": "http://localhost:3000/example.html"
    },
    {
      "type": "waitFor",
      "value": "1500"
    }
  ],
  "annotate": [
    {
      "type": "rectangle",
      "offset": 2,
      "width": 2,
      "selectors": [
        "p"
      ]
    }
  ]
}

Example 4: Targeting nested iframe ​

The screenshot endpoint supports an iframe within an iframe, you can target the nested iframe by specifying the frame position. As an example, let's consider a page with nested iframe as follows:

Top Frame
├── Frame One
│   └── Frame Two
│       ├── Frame Three
│       └── Frame Four
└── Frame Five
└── Frame Six

Here's a summary how you would what value would be used for the frame parameter:

Frame nameFrame value
Frame One[0]
Frame Two[0,0]
Frame Three[0,0,0]
Frame Four[0,0,1]
Frame Five[1]
Frame Six[2]

In terms of code, targeting a p tag in Frame Two, the request would look like this:

POST /screenshot

json
{
  "deviceScaleFactor": 1,
  "steps": [
    {
      "type": "navigate",
      "url": "http://localhost:3000/example.html"
    },
    {
      "type": "waitFor",
      "value": "1500"
    },
    {
      "type": "click",
      "selectors": [
        "p"
      ],
      "frame": [
        0,
        0
      ]
    }
  ]
}