Screenshot API · Use case

Take a dark mode screenshot of any website

A dark mode screenshot used to mean toggling a system setting and capturing by hand. Design reviews, documentation, app store listings and marketing pages now need both themes of every page, kept in sync. Tell the browser which color scheme to prefer and the Screenshot API captures the dark or the light variant directly, with every other option unchanged.

Start with the Screenshot API

A demo page captured with its dark theme active — Generated live by the API call below with colorScheme set to dark.

The problem

Automated screenshots ignore dark mode and come back light

Most sites switch themes with the prefers-color-scheme media query, which follows the operating system. A headless browser reports no preference, so every automated capture comes back in the default theme, even for a product whose users mostly see the dark one.

The workarounds do not scale. Changing the OS setting on a capture machine affects every job on it. Appending a theme query string only works on sites that invented one. Forcing dark colors with your own CSS produces a page no visitor has ever seen.

The colorScheme parameter sets that media feature for the request: no-preference by default, or light or dark. Sites that implement prefers-color-scheme render the matching theme, and the capture is otherwise identical. It is one of the rendering conditions covered in the browser settings guide, next to the viewport and the device.

How it works

How to screenshot a website in dark mode

One option covers every site that follows the system preference. For a site that stores the theme itself, trigger its switch with a click or apply its theme class with injected CSS.

1 · Force dark mode

import createClient from 'microlink.io'

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

const { url } = await microlink.screenshot('https://example.com', {
  colorScheme: 'dark'
})

The browser reports prefers-color-scheme: dark, the site renders its dark theme, and the response carries the hosted image URL.

2 · Capture both themes for a comparison

import createClient from 'microlink.io'

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

const themes = ['light', 'dark']

const [light, dark] = await Promise.all(
  themes.map(colorScheme =>
    microlink.screenshot('https://example.com', { colorScheme })
  )
)

Two parallel requests return two images. The cache key includes every query parameter, so each theme gets its own cache entry.

3 · Dark mode on a phone

import createClient from 'microlink.io'

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

const { url } = await microlink.screenshot('https://example.com', {
  colorScheme: 'dark',
  device: 'iPhone 15 Pro'
})

colorScheme composes with device emulation, so the dark mobile variant takes one request.

4 · The same request as a URL

curl 'https://api.microlink.io/?url=https%3A%2F%2Fexample.com&screenshot=true&meta=false&colorScheme=dark'

This works on the free endpoint with no API key. meta=false skips metadata detection, which is the biggest speedup for screenshot-only requests.

Parameters used

colorScheme Sets the prefers-color-scheme media feature: no-preference (default), light or dark.
click Clicks a site-specific theme switch before the capture.
styles Injects CSS to apply a theme when the site ignores the media query.
device Combine with a phone preset for the mobile dark theme. Defaults to Macbook Pro 13.

colorScheme only affects sites that implement prefers-color-scheme. CSS animations and transitions are disabled by default for screenshots, which keeps themed captures stable from one run to the next.

Why it works

Why emulate prefers-color-scheme for dark mode captures

A theme is a rendering condition, like a viewport. Treating it as a request option is what makes a prefers-color-scheme screenshot API repeatable.

01 · Standards based

The same signal real visitors send.

colorScheme sets the media feature the site already listens to. There is nothing site-specific to reverse engineer for any page that follows the platform convention, and nothing to maintain when the site redesigns its toggle.

Combine it with mobile device emulation to get the dark mobile variant, the one designers usually check last.

02 · Comparable output

Light and dark captures share every other setting.

The theme is one option among many, so the two captures have the same viewport, the same waits and the same blocked ads. A side-by-side comparison shows theme differences only, which is what a visual regression suite needs.

Running both themes from the same job is a map over two values, and there is no throttling on parallel requests.

03 · Escape hatch

click and styles cover custom toggles.

Sites that persist the theme in local storage or a cookie ignore the media query. Click their switch, or inject the rules their dark theme uses, and the capture happens after the change applies.

When not to: if the site has no dark theme at all, colorScheme has no effect, and forcing dark colors with CSS produces a screenshot no visitor will ever see. For a dark presentation of a light page, put it in a dark browser frame instead.

FAQ

How do I take a dark mode screenshot of a website?

Add colorScheme=dark to the request. The browser reports prefers-color-scheme: dark and any site that implements that media query renders its dark theme before the capture.

Why does my dark mode screenshot still look light?

The site probably does not implement prefers-color-scheme, or it stores the theme in a cookie or local storage. Use click to activate its toggle, or styles to apply its dark theme rules, then capture.

Can I capture light and dark screenshots in one request?

No, one request produces one image. Send two requests with colorScheme set to light and dark. They run in parallel and are cached independently.

Can I take a dark mode screenshot of the mobile version of a site?

Yes. colorScheme is a browser setting for the whole request, so it combines with a device preset or a custom viewport. The mobile screenshot tool lets you preview the phone layout first.

Are dark mode screenshots available on the free plan?

Yes. colorScheme works on every plan, including the free endpoint with 25 requests per day. See pricing when you need more volume.

Related use cases

Solve the next problem with the same API

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

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

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

Ready to capture dark mode?

One option, both themes, every plan. Start on the free endpoint and capture the dark variant of your first page today.

Capture in dark mode