Docs / Parameters / Wait For Selector Parameter

Wait For Selector Parameter

The wait_for_selector parameter allows you to wait for a specific CSS selector to be present in the DOM before capturing the image.

Specifications

Property	Value
Type	string
Required	No
Default	null
API	Both HTML/CSS and Screenshot APIs

Description

The Wait For Selector parameter:

Delays screenshot capture until the specified element is found in the DOM
Useful for ensuring dynamic content is loaded before capture
Works with any valid CSS selector
Times out if the selector is not found within a reasonable time

This parameter does not work with elements inside iframes. If you’re using third-party widgets or embedded content that loads in an iframe (like social media embeds, payment forms, or chat widgets), you should use the ms_delay parameter instead.

Use this parameter when you need to:

Wait for dynamically loaded content
Ensure specific elements are rendered before capture
Capture content that depends on API responses
Wait for lazy-loaded images or components

Examples

Wait for Dynamic Content

{
    "url": "https://example.com",
    "wait_for_selector": "#dynamic-content"
}

Wait for Multiple Elements

{
    "html": "<div id='app'></div>",
    "wait_for_selector": "#app .loaded.ready"
}

Wait for Lazy-Loaded Image

{
    "url": "https://example.com",
    "wait_for_selector": ".hero-image[src]"
}

Common Use Cases

Waiting for content loaded by JavaScript frameworks
Ensuring API-dependent content is rendered
Capturing after lazy-loaded images appear
Waiting for UI components to fully initialize

Limitations

Key limitations to be aware of:

Does not detect elements inside iframes
Cannot wait for elements in embedded third-party content
Will timeout if the selector never appears
Only checks for presence in DOM, not visual rendering

Alternative Approaches

If you need to wait for iframe content or third-party widgets, consider:

Using the ms_delay parameter with an appropriate delay
Implementing a custom loading indicator in the main document
Using JavaScript to detect the loaded state of embedded content

Documentation