Home / Docs / Parameters / selector parameter | HTML to Image Docs

Selector Parameter

The selector parameter allows you to capture a specific element on the page instead of the entire viewport.

Specifications

Property	Value
Type	string
Required	No
Default	null
API	Screenshot API only

Description

The selector parameter:

Uses CSS selectors to target specific elements
Captures only the selected element and its children
Preserves the element’s styles and layout
Useful for capturing specific components or sections

The selector must match exactly one element on the page. If multiple elements match or no elements are found, the API will return an error.

Examples

Basic Element Selection

{
    "url": "https://example.com",
    "selector": "#main-content"
}

Complex Selector

{
    "url": "https://example.com",
    "selector": ".article-container .content:first-child",
    "dpi": 2
}

Combining with Other Parameters

{
    "url": "https://example.com",
    "selector": ".product-card",
    "css": ".product-card { border: 2px solid blue; }",
    "webhook_url": "https://your-domain.com/webhook"
}

Common Selectors

Here are some commonly used selector patterns:

Selector	Description	Example
#id	Select by ID	”#header”
.class	Select by class	”.content”
tag	Select by tag name	”main”
[attr]	Select by attribute	”[data-section=‘hero’]“
Combined	Multiple selectors	”.container .card:first-child”

Best Practices

Use Specific Selectors

Prefer IDs when possible
Use unique class combinations
Avoid overly complex selectors

Verify Element Existence

Ensure the selector matches exactly one element
Test with different page states
Handle dynamic content appropriately

Consider Layout

Check element positioning
Account for responsive designs
Test different viewport sizes

The selector parameter only works with the Screenshot API. For the HTML API, structure your HTML to include only the content you want to capture.

For dynamic websites, the selected element must exist before capture. Combine with wait_for_selector for reliable timing.

Common values

#main-content - capture the main content region by ID.
article - capture an <article> element on a page that has only one.
[data-section='hero'] - capture by data attribute when classes are unstable.
.product-card - works only when the class appears exactly once on the page.

When to use

Use selector when you want to capture a single component out of a larger page. Common cases: a chart widget, a pricing table, a property card on a real estate site, a tweet embed. For full-page captures, use fullpage instead.

Common mistakes

Selector matches multiple elements. The API returns an error. Make the selector unique with an ID or :nth-of-type().
Selector matches nothing. Often because the element loads after capture. Pair with wait_for_selector or ms_delay.

Templates that use this parameter

Selector capture pairs with these templates when you want to extract a single element from a wider page:

Documentation