Screenshot API · Use case

Screenshot a single element of a page by its CSS selector

To screenshot an element by CSS selector, you name the node and the API returns an image of exactly that box. No full-page capture, no cropping math. It fits a chart headed for a weekly report, a pricing table in a competitor comparison, a component in your documentation or a widget in a changelog. The screenshot.element option crops the capture to the matching node and waits until it is visible.

Start with the Screenshot API

The result frame of a CodePen captured as a single element — Generated live by the API call below: only the #result-iframe-wrap element is captured.

The problem

Cropping a full-page screenshot by coordinates is guesswork

You rarely need the whole viewport. You need the revenue chart, the plan comparison or the embedded map, at its real size, every day. A full capture forces a second step: find where the element landed and cut it out.

Cropping by coordinates breaks the moment the page adds a banner, swaps a font or renders at a different width. You end up with half a chart or a strip of the neighboring section. Image-processing code to detect the region is a second system to maintain, and it still fails when the element renders late.

Selecting the node is stable. With screenshot.element the browser finds the element, waits for it to appear and be visible, and captures exactly its box. Add omitBackground and the default white background is dropped, so the image comes back transparent around the element.

How it works

How to screenshot an element with a CSS selector

One option selects the node. Combine it with the interaction options when the element sits behind a tab or an accordion. The customizing output guide compares element capture with full-page and viewport captures.

1 · Capture the element

import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const { url, width, height } = await microlink.screenshot(
  'https://example.com/pricing',
  { element: '#pricing-table' }
)

The capture is cropped to the element matching the selector. The response includes the hosted image URL plus the width and height of the cropped image.

2 · Make the background transparent

import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const { url } = await microlink.screenshot('https://example.com', {
  element: '.logo',
  omitBackground: true
})

omitBackground drops the default white background. Keep the default PNG type, because JPEG has no transparency.

3 · Open a tab first, then capture

import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const { url } = await microlink.screenshot('https://example.com/pricing', {
  click: '#tab-annual',
  element: '#pricing-table'
})

click changes the page state before the capture, so the element is captured the way it looks after the interaction.

4 · The same request as a URL

curl 'https://api.microlink.io/?url=https%3A%2F%2Fexample.com%2Fpricing&meta=false&screenshot.element=%23pricing-table'

Dot notation turns nested screenshot options into query parameters, so screenshot.element works from any language or straight from an img tag.

Parameters used

screenshot.element CSS selector of the element to capture. Waits for it to appear and be visible.
screenshot.omitBackground Omits the default white background for a transparent capture. Off by default; PNG only.
click Clicks a selector first, to open the tab or accordion that contains the element.
scroll Scrolls to a selector while keeping a viewport-sized capture, for a section shown in context.

element crops the image; scroll only moves the viewport. Use element for a widget and scroll for a section you want to show with its surroundings.

Why it works

Why a selector beats cropping a full screenshot

The selector is a contract with the page, not with its pixels. That gives a screenshot of a specific element three practical advantages.

01 · Waits for visibility

No blank captures of elements that have not rendered yet.

The API waits for the element to appear and be visible before it captures. Client-rendered charts and lazy-loaded widgets are captured after they draw, without a fixed delay. You usually do not need an extra waitForSelector for the same node.

When the element depends on data that arrives later, the JavaScript-rendered pages recipe covers waiting for a child selector or a network event.

02 · Smaller and faster

You transfer the pixels you need and nothing else.

An element capture is usually faster than a full-page capture and produces a smaller image. That means lighter files in reports and docs, and less storage when you keep a daily history of the same chart.

The response still reports the width and height of the image, so it drops into a layout without measuring. Compare the options in the full page capture reference.

03 · Transparent output

omitBackground turns a component into an asset.

Logos, icons and UI components captured as a transparent screenshot composite over any color in a slide, a social card or a design comp. The page’s own transparent areas are preserved instead of being filled with white.

When not to: if a sticky header or a modal covers the element, the overlap shows up in the capture. Hide it with styles or dismiss it with click first, as in the cookie banner recipe.

FAQ

How do I screenshot a specific element with a CSS selector?

Pass the selector as screenshot.element, for example screenshot.element=#pricing-table in the URL or element: '#pricing-table' in the SDK. The API waits for the node to be visible and returns an image cropped to its box.

What if my element screenshot selector matches several nodes?

The capture targets one element, so write a selector that matches exactly one node: an id, a data attribute or a parent selector that wraps the part you want. Test the selector in the browser console before you automate it.

Can I screenshot an element inside an iframe?

Select the element that wraps the iframe and the capture includes what is rendered inside it, which is how the CodePen example on this page works. A CSS selector does not reach into the iframe’s own document.

Why is my element screenshot blank or cut off?

The API waits for the element to be visible, but a sticky header or a modal can still overlap it. Hide the overlap with styles or dismiss it with click before capturing.

If the element renders only after an interaction, click the trigger first. The screenshot troubleshooting guide lists the fix for each wrong-area symptom.

Can I get a transparent screenshot as JPEG?

No. JPEG has no alpha channel, so omitBackground only produces transparency with the default PNG type. Switch to JPEG when you care more about file size than transparency.

Related use cases

Solve the next problem with the same API

Screenshots without cookie banners or ads

Ads, trackers and consent popups are blocked before the page renders, and one option dismisses first-party banners.

Block cookie banners and ads

Screenshots of JavaScript-rendered pages

Wait for a selector, a lifecycle event or a delay so single-page apps and lazy sections finish rendering before capture.

Capture JavaScript-rendered pages

Mobile screenshots at any viewport

Emulate an iPhone, a Pixel, an iPad or any custom viewport and capture the page exactly as those visitors see it.

Capture mobile screenshots

Faster, smaller screenshots

Skip metadata, pick JPEG quality and pixel density, and wait for a selector instead of a timer to cut time and bytes.

Speed up your screenshots

Screenshots with a browser frame

Wrap the capture in a light or dark browser window over a color, gradient or image background.

Add a browser frame

Clean Markdown, no boilerplate

Convert only the article body: one selector keeps navigation, ads and widgets out of the Markdown.

Get clean Markdown

Ready to capture just the element?

One selector, one image, no cropping math. Start on the free endpoint and capture a chart, a table or a component in a single call.

Capture an element