---
title: "selector parameter"
description: "Capture only a specific element by CSS selector instead of the full viewport."
url: "https://html2img.com/docs/parameters/selector/"
---

# Selector Parameter

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

> **Note**
>
> `selector` is ignored when [`format`](https://html2img.com/docs/parameters/format/) is `pdf`: the whole document is captured and paginated.

## Specifications

| Property | Value |
|----------|-------|
| Type | string |
| Required | No |
| Default | null |
| Max length | 255 characters |
| 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

> **Important**
>
> If several elements match, the first match in the document is captured - so make the selector specific enough to target the element you mean. If nothing matches within 5 seconds, the render fails with an error.

## Examples

### Basic Element Selection
```json
{
    "url": "https://example.com",
    "selector": "#main-content"
}
```

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

### Combining with Other Parameters
```json
{
    "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

1. **Use Specific Selectors**
 - Prefer IDs when possible
 - Use unique class combinations
 - Avoid overly complex selectors

2. **Verify Element Existence**
 - Make the selector specific - the first match wins when several elements match
 - Test with different page states
 - Handle dynamic content appropriately

3. **Consider Layout**
 - Check element positioning
 - Account for responsive designs
 - Test different viewport sizes

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

> **Note**
>
> For dynamic websites, the selected element must exist before capture. Combine with [wait_for_selector](https://html2img.com/docs/parameters/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](https://html2img.com/docs/parameters/fullpage/) instead.

## Common mistakes

- **Selector matches multiple elements.** The first match in the document is captured, which may not be the one you meant. Target an ID or a unique `data-` attribute to be sure.
- **Selector matches nothing.** Often because the element loads after capture. Pair with [wait_for_selector](https://html2img.com/docs/parameters/wait_for_selector/) or [ms_delay](https://html2img.com/docs/parameters/ms_delay/).

See also: [twitter-embed example](https://html2img.com/docs/examples/twitter-embed/), [facebook-post example](https://html2img.com/docs/examples/facebook-post/), [getting started guide](https://html2img.com/docs/getting-started/).

## Templates that use this parameter

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

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