Element Screenshot API: Capture Specific UI Components with CSS Selectors

Why this is timely

Browser automation is becoming more targeted. Playwright documents screenshot capture at both page and locator level, which matches the way developers debug individual components instead of whole pages. The current Playwright MCP documentation also exposes screenshot workflows for AI agents, including screenshots tied to element references. Chrome's DevTools for agents guidance, updated in May 2026, shows the same direction: agents need inspectable page state, emulation, and page-level evidence rather than only raw navigation.

SnapshotFlow fits the API side of that workflow. The backend verifies the target URL, renders it in Chromium, waits for wait_for_selector, can click a selector, inject CSS or JavaScript, hide noisy elements, and then capture only the element matched by selector. The Node SDK exposes the same capability as camelCase options such as waitForSelector, selector, click, and hideSelectors.

When an element screenshot is better than a full page

Use selector-based capture when the target is a specific rendered component and the surrounding page would make the evidence harder to review.

1. Capture one element with cURL

Start with a selector that exists after the page finishes rendering. Use wait_for_selector to avoid racing the app, then use selector to crop the final screenshot to that element.

Expected behavior: SnapshotFlow validates the URL, opens it in Chromium, waits for the Pro pricing card, crops the screenshot to that element, stores the WebP, and returns a plain-text download URL. If the selector never appears, the API returns SELECTOR_NOT_FOUND with HTTP 422 instead of returning a misleading full-page image.

2. Capture a component with the Node SDK

The official Node SDK is a thin HTTP wrapper over the SnapshotFlow API. It accepts camelCase option names and converts them to the API's snake_case parameters.

Save a binary component image

Use take() when your job writes the image into local storage, S3, a ticket attachment, or an internal report pipeline.

3. Common selector screenshot patterns

Capture a post-click state

For menus, tabs, accordions, and modals, click one selector before cropping another selector.

Render private HTML and crop one widget

If the component does not have a public URL, pass raw HTML through the SDK. The SDK base64-encodes the HTML before sending it to the API.

Choose selector before clip coordinates

SnapshotFlow also supports clip_x, clip_y, clip_width, and clip_height. Use those when the target is a fixed coordinate region, such as a canvas area. For normal web UI, selector is safer because it follows layout shifts across responsive widths.

Operational advice and edge cases

• Prefer test-oriented selectors. A stable data-testid, data-snapshot, or semantic component class is less brittle than a deeply nested CSS path.
• Use wait_for_selector and selector together. Waiting for the same element you capture makes failures easier to interpret.
• Expect one matching element. If the selector matches multiple elements, the browser captures the first match. Make the selector specific when evidence quality matters.
• Clean the frame deliberately. hide_selectors, block_ads, block_trackers, and block_cookie_banners are useful when overlays are not the subject of the screenshot. Do not hide UI that reviewers need to inspect.
• Use cache=false during investigation. Cached captures are useful for repeated reads, but a fix verification run should request a fresh render.
• Keep viewport settings explicit. Element size and wrapping depend on width, height, device_scale_factor, and mobile emulation. Store those settings next to the image URL.
• Do not use selector screenshots for PDF output. SnapshotFlow's selector crop is for image capture. For PDFs, use format=pdf with PDF options and capture the page print output instead.

FAQ

Can I capture an element inside a page that requires JavaScript?

Yes. SnapshotFlow renders pages in Chromium. Use wait_until=networkidle2 or a more specific wait_for_selector so the app hydrates before the element crop happens.

What happens if the selector is missing?

The API returns SELECTOR_NOT_FOUND with HTTP 422 for missing selector, click, or wait_for_selector targets. Treat that as a useful signal that the page changed, the selector is wrong, or the wait condition is too early.

Can I use this for visual regression testing?

Yes, but the comparison workflow is separate. Capture a stable element as a baseline, then use the visual regression guide for thresholds, diffs, and CI behavior.

Sources and further reading

• Playwright screenshot documentation for page and locator screenshot workflows.
• Playwright MCP documentation for current browser automation tools used by agents.
• Chrome DevTools for agents: emulate user experiences, updated May 13, 2026.
• W3C WebDriver BiDi specification for browser automation protocol context.
• MDN CSS selectors reference for selector syntax used by selector, wait_for_selector, and click.

Next step

If your workflow needs component-level evidence, start with one stable selector and one known viewport. After the first capture is reliable, add click, hide, cache, and response-type settings only for the states your reviewers actually need.