Docs / Parameters / wait_for_selector parameter | HTML to Image Docs

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:

Use the ms_delay parameter with a fixed delay
Add a custom loading marker in the main document and wait for it instead
Use JavaScript in your HTML to detect the loaded state of embedded content

Common values

body[data-ready='true'] - your own marker, set after data fetches complete.
.chart-rendered - a class added by your chart library on first paint.
#app .ready - an element your single-page app renders once mounted.
.hero-image[src] - wait until a lazy-loaded image has its src set.

When to use

Use wait_for_selector when your content depends on JavaScript that runs after page load, and you control the markup or selector. It is more efficient than ms_delay because it returns as soon as the element appears, not after a fixed wait.

Common mistakes

Using on iframe content. The selector cannot see inside iframes. Use ms_delay for embeds.
Using a selector that already exists at page load. The wait returns immediately and your dynamic content has not rendered. Use a marker that only appears after the data is ready.

Documentation