Screenshot API · Use case

Wrap a website screenshot in a browser frame, ready to share

A screenshot with a browser frame reads as a finished asset: window chrome, breathing room and a background in your brand color. Designers build that browser window mockup by hand for every launch post, changelog entry, pitch deck and docs page. The screenshot.overlay option does the composition inside the Screenshot API, so the framed image comes straight from a URL.

Start with the Screenshot API

A website capture composed inside a dark browser frame over a gradient — Generated live by the API call below with a dark browser frame over a gradient background.

The problem

A raw website screenshot needs a design pass before it ships

Edge-to-edge captures have no context: no window chrome, no margin, no brand color behind them. Dropped into a slide or a blog post they look like a debugging artifact, so every marketing asset takes a detour through a design tool for the same five-minute edit.

That manual step is exactly what automation skips. A changelog that publishes itself, a directory with thousands of listings or a release email built in CI cannot wait for someone to open a mockup template. Compositing the frame yourself means an image library, a window asset in two themes and code to scale them to every viewport.

With screenshot.overlay the API wraps the capture in a browser window, light or dark, and places it over a background you choose: a hex, rgb or rgba color, a CSS gradient or an image URL. The result is one hosted image. The customizing output guide shows the overlay next to the other output options.

How it works

How to add a browser frame to a website screenshot

Two properties control the composition: browser picks the window theme and background fills the space around it. They combine with a viewport, a device or the JPEG options like any other capture.

1 · Dark frame over a gradient

import createClient from 'microlink.io'

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

const { url } = await microlink.screenshot('https://example.com', {
  overlay: {
    browser: 'dark',
    background: 'linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)'
  }
})

browser accepts light or dark, and background takes a color, a CSS gradient or an image URL. The response carries the hosted URL of the composed image.

2 · Light frame over a brand color as JPEG

import createClient from 'microlink.io'

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

const { url } = await microlink.screenshot('https://example.com', {
  overlay: { browser: 'light', background: '#0473e4' },
  type: 'jpeg',
  quality: 80
})

Switch to JPEG with quality when the asset goes on a web page and file size matters. Quality runs from 0 to 100 and defaults to 80.

3 · Frame a mobile capture

import createClient from 'microlink.io'

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

const { url } = await microlink.screenshot('https://example.com', {
  device: 'iPhone 15 Pro',
  overlay: { browser: 'dark', background: '#0473e4' }
})

Every capture option runs before the frame is added, so a device preset produces a framed phone-sized capture.

4 · The same request as an image URL

curl 'https://api.microlink.io/?url=https%3A%2F%2Fexample.com&meta=false&embed=screenshot.url&screenshot.overlay.browser=dark&screenshot.overlay.background=%230473e4'

Nested options flatten to screenshot.overlay.browser and screenshot.overlay.background. With embed the URL returns the image itself, ready for an img tag or a Markdown file.

Parameters used

screenshot.overlay browser: light or dark. background: hex, rgb or rgba color, CSS gradient or image URL.
screenshot.type Image format of the composed asset: png (default) or jpeg.
screenshot.quality JPEG compression from 0 to 100, default 80. Ignored for PNG.
device Frames a phone or tablet capture for app and responsive showcases.
embed Returns the composed image as the response body instead of JSON.

A malformed background, such as a gradient with missing color stops, is rejected with the EINVALOVERLAYBG error code. A typo fails fast instead of producing a broken asset.

Why it works

Why compose the browser mockup inside the API

The frame is the difference between a debug artifact and a marketing asset. Doing it server-side turns a website screenshot browser mockup into something a build step can produce.

01 · One request, one asset

No design tool in the loop.

Changelogs, launch posts, product tours and documentation can generate their framed screenshots at build time or on demand, with the same options every time. The output is a hosted image, cached for 24 hours by default.

The same URL powers dynamic Open Graph images once you add embed.

02 · On brand

Backgrounds accept your palette or your artwork.

Use a flat brand color for consistency, a gradient for launch material, or an image URL to place the window over a scene. The light and dark window themes let you match the page you are framing.

Pair a dark frame with a dark mode capture for a fully dark composition, or pull the background from the site’s own brand colors.

03 · Still a screenshot

Every capture option applies before the frame is added.

Wait for content, hide banners, emulate a phone or switch the color scheme, then frame the result. The overlay is the last step of the same request, not a separate product with its own options.

When not to: if the image is a pixel-accurate reference for QA or visual regression, skip the overlay. The frame adds chrome and background that are not part of the page.

FAQ

How do I add a browser frame to a website screenshot?

Pass screenshot.overlay with a browser theme, light or dark, and optionally a background. The API captures the page first and then composes it inside the browser window, returning one image.

Which backgrounds can I put behind a framed screenshot?

Solid colors as hex, rgb or rgba, CSS gradients such as linear-gradient, and image URLs. A malformed value returns the EINVALOVERLAYBG error, usually because of missing gradient color stops or an invalid color.

What size is a screenshot with a browser frame?

The composed image includes the window chrome and the background around the capture, so do not assume it matches the viewport. Read width and height from the response before placing it in a layout.

Can I put a mobile screenshot inside the browser frame?

Yes. Set device to a phone preset or pass a custom viewport, and the overlay wraps that capture in the same window style. See the mobile screenshot recipe for the device options.

Can I get the framed screenshot as an image, without JSON?

Add embed=screenshot.url and the API URL returns the PNG or JPEG itself, ready for an img tag, a Markdown file or an og:image tag. The delivery and embedding guide covers each context.

Related use cases

Solve the next problem with the same API

Dynamic Open Graph images

Point og:image at an API URL and every share shows a current, cached screenshot of the page.

Generate Open Graph images

Screenshots in dark mode

Set prefers-color-scheme before the capture and get the dark or light theme of any page that supports it.

Capture dark mode

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

Screenshot a single element

Crop the capture to one CSS selector, such as a chart or a pricing table, with a transparent background if you need it.

Capture a single element

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

Brand colors from images

Get the dominant palette and an accessible text and background pair from a site’s logo and preview image.

Extract brand colors

Ready for presentation-ready captures?

A frame and a background in one option, no design tool needed. Start on the free endpoint and produce your first framed screenshot today.

Frame a screenshot