---
title: "wait_for_selector parameter"
description: "Wait for a specific element to appear in the DOM before capturing the page."
url: "https://html2img.com/docs/parameters/wait_for_selector/"
---

# 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

> **Warning**
>
> 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.

> **Tip**
>
> 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
```json
{
    "url": "https://example.com",
    "wait_for_selector": "#dynamic-content"
}
```

### Wait for Multiple Elements
```json
{
    "html": "<div id='app'></div>",
    "wait_for_selector": "#app .loaded.ready"
}
```

### Wait for Lazy-Loaded Image
```json
{
    "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

> **Important**
>
> 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:
1. Use the [ms_delay](https://html2img.com/docs/parameters/ms_delay/) parameter with a fixed delay
2. Add a custom loading marker in the main document and wait for it instead
3. 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](https://html2img.com/docs/parameters/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.

See also: [chart-screenshot example](https://html2img.com/docs/examples/chart-screenshot/), [getting started guide](https://html2img.com/docs/getting-started/).

## Templates that use this parameter

Templates rendering complex external content rely on a stable selector before capture:

- [Code screenshot template](https://html2img.com/templates/code-screenshot/)
- [GitHub social preview template](https://html2img.com/templates/github-social-preview/)
- [Tweet mockup card template](https://html2img.com/templates/tweet-mockup-card/)