Skip to content
ExplainerBy 9 min read

How to screenshot a website in dark mode

A dark screenshot is the same page with one answer changed: what the browser says when the site asks whether the visitor prefers dark. Wipe between night and day, then see why some pages never change.

example.com

Dark

Light

Drag the line on the page, or use the slider. Same page, same layout: only the colours change.

One miniature web page shown in its dark theme and in its light theme. The layout is identical in both; the colours, the picture, the search field and the scrollbar change.

How does a website decide to be dark?

A website turns dark when a dark preference travels from the operating system, through the browser, into a CSS media query that the site’s styles listen to. A dark screenshot fails when that signal is lost somewhere on the way, and there are only two places where it can be.

  1. 1

    Operating system

    The visitor picks light or dark once, in the system settings.

  2. 2

    Browser

    The browser passes the setting on to every page it opens.[1]

    A capture tool steps in. DevTools, Playwright, Puppeteer and screenshot APIs override the setting here. That is emulation.

  3. 3

    Media query

    (prefers-color-scheme: dark) becomes true or false inside the page.[1]

  4. 4

    The site’s CSS

    Rules inside the media query, or light-dark() values, swap the colours.[4]

    It can break here. No dark rules, or rules that follow a class on <html> and not the media query: the signal arrives and nothing listens.

  5. 5

    The painted page

    The browser draws the page, plus its own parts: form controls, scrollbars, the canvas behind the page.[2]

    It can break here. Without color-scheme, the browser’s own parts stay light on a dark page.

The signal path of a dark preference, from the system setting to the painted page. Blue: where a capture tool steps in. Amber: where the signal can be lost.

The three switches, and which one a capture tool can flip

Every website uses one of three switches for its dark theme, and emulation reaches only the first. Knowing which switch a site has tells you in advance whether a dark screenshot will work.

  1. Switch 1Emulation flips it

    The media query

    The site’s CSS asks prefers-color-scheme and changes its colours when the answer is dark.[1]

    Flipped by
    The operating system setting, or a browser setting, on the visitor’s device.
    Remembered in
    Nowhere on the site. It is read fresh on every visit.
    Can a capture tool flip it?
    Yes. Emulation sets the answer directly, with no change to the machine that takes the screenshot.
  2. Switch 2Emulation does not reach it

    A class or attribute on <html>

    The site’s own theme button runs a script that sets something like class="dark" or data-theme="dark", and the CSS follows that.

    Flipped by
    The visitor, by pressing the site’s button.
    Remembered in
    In that browser only: localStorage or a cookie for that site.
    Can a capture tool flip it?
    Not by emulation. Press the button, send the cookie, or set the class with a script. Many of these sites start from the media query until a visitor chooses, and a capture tool is always a first-time visitor, so try emulation first.
  3. Switch 3Nothing to flip

    No dark theme at all

    The site has one set of colours. A browser may darken it by itself: Chrome on Android introduced Auto Dark Theme in Chrome 96 as an origin trial, which applies a generated dark theme to light sites.[5][2]

    Flipped by
    Nothing on the site. Only a browser feature that repaints it.
    Remembered in
    Not applicable. A site opts out of forced darkening with color-scheme: only light.
    Can a capture tool flip it?
    No. The page looks the same with a dark preference. The only way to a dark screenshot is to repaint it with your own CSS.

Why did my dark screenshot come out light?

A dark screenshot comes out light, or only partly dark, for seven reasons, and each one leaves a recognisable mark on the image. Find the look, then the row.

  • Stays light

    Nothing changed at all.

  • Bright image

    One white rectangle in a dark page.

  • Lost logo

    Dark ink on a dark background.

  • Light controls

    White field and scrollbar.

Why a dark mode screenshot comes out light or partly light: symptom, cause and fix
SymptomCauseFix
The whole page stays lightLooks like: stays lightCauseThe dark theme is switched by a class or attribute on <html> that the site’s own button sets. The CSS never asks the media query. Or the site has no dark theme.FixPress the site’s theme button before the capture, or set the class yourself with a script. If there is no dark theme, only your own CSS can darken the page.
Dark in your browser, light in the captureLooks like: stays lightCauseYou once chose dark on that site, and it saved the choice in localStorage or a cookie in your browser. A capture tool starts with empty storage, so the site treats it as a new visitor.FixSend the cookie the site uses for its theme, or set the class with a script. Sites that fall back to the media query for new visitors only need emulation.
Light, or half light, on a site that turns dark a moment laterLooks like: stays lightCauseThe page paints once in its default colours and a script switches the theme afterwards. A screenshot taken in that gap records the flash.FixCapture later: wait for an element or class that only exists in the dark theme, or add a short delay. Site owners: put <meta name="color-scheme"> in the head before any CSS and set the theme class in an inline script in the head.[2][3]
A bright rectangle glares in a dark pageLooks like: bright imageCauseA photo, chart or screenshot with a white background has no dark variant. An image does not change with the theme unless the site supplies a second file.FixSite owners: add a dark file with <picture> and <source media="(prefers-color-scheme: dark)">, or give light-dark() two images in CSS. For someone else’s page, soften images with a CSS filter of your own.[12][4]
A logo or icon disappearsLooks like: lost logoCauseA transparent PNG or SVG drawn in dark ink now sits on a dark background.FixSupply a light variant the same way as for photos, draw inline SVG icons with currentColor so they take the text colour, or put a light plate behind the image.[12]
Text fields, checkboxes and scrollbars stay lightLooks like: light controlsCauseThe page does not declare color-scheme, so the browser keeps drawing its own parts in light colours: form controls, scrollbars and the canvas behind the page.FixSite owners: :root { color-scheme: light dark; }. For a capture of someone else’s page, add :root { color-scheme: dark; } as custom CSS.[2]
A transparent screenshot of a dark page is unreadable in a documentCauseA capture with a transparent background drops the dark backdrop but keeps the light text, which then lands on the white page of the document.FixKeep the background when you capture a dark theme, or place the image on a dark surface.

A quick test for any site

Open the site in a private window, so nothing is remembered, and switch dark mode on with the developer tools. If the page turns dark, it follows the media query and emulation will work in any capture tool. If it stays light and has a theme button, it is switch 2.

How to turn on dark mode by hand

Dark mode can be switched on in two places: in the developer tools of one browser tab, or in the system settings of the whole device. For a screenshot, the developer tools are quicker, because nothing else on the screen changes.

In one browser tab, with developer tools

Only the open tab turns dark. Nothing else on the computer changes.

In one browser tab, with developer tools
WherePath
Chrome DevToolsRendering tab›Emulate CSS media feature prefers-color-scheme›prefers-color-scheme: dark[6][7]Open the Rendering tab from More options > More tools > Rendering, or press Ctrl+Shift+P (Cmd+Shift+P on a Mac), type "rendering" and choose Show Rendering.
Firefox DevToolsPage Inspector›Rules view toolbar›the two buttons that enable the light and the dark preference[8]Selecting one button deselects the other. With neither selected, emulation is off.
Safari Web InspectorElements tab›Override user preferences›color scheme[9]The same popover overrides reduced motion and increased contrast.

For the whole device, in system settings

Every app and every site that follows the setting turns dark.

For the whole device, in system settings
WherePath
macOSSystem Settings›Appearance›Light, Dark or Auto[13]Auto follows the Night Shift schedule.
WindowsSettings›Personalization›Colors›Choose your mode›Light, Dark or Custom[15]
iPhone and iPadSettings›Appearance›Dark[14]In iOS 26 and earlier the options are under Settings > Display & Brightness.
AndroidSettings›Display›Dark theme[16]On some devices the menu is called Display & touch.

Once the page is dark, take the screenshot the usual way. The steps for each system are in how to take a full page screenshot on every device.

The CSS for a site that supports both themes

A site supports both themes correctly when it does three things: declares color-scheme, follows the media query, and lets its own theme button override both. A site built this way turns dark for visitors and for every capture tool.

styles.css, with the media query
:root {
  color-scheme: light dark;
  --page: #ffffff;
  --text: #1a1a1a;
}

@media (prefers-color-scheme: dark) {
  :root {
    --page: #121212;
    --text: #ededed;
  }
}

body {
  background: var(--page);
  color: var(--text);
}
The classic way: colours in custom properties, replaced inside the media query.[1]
styles.css, with light-dark()
:root {
  color-scheme: light dark;
}

body {
  background: light-dark(#ffffff, #121212);
  color: light-dark(#1a1a1a, #ededed);
}

/* A theme button only has to set the scheme. */
:root[data-theme='light'] { color-scheme: light; }
:root[data-theme='dark']  { color-scheme: dark; }
The short way: light-dark() holds both values and follows color-scheme, so a theme button only has to set the scheme.[4]
index.html
<head>
  <!-- Before any CSS, so the first paint is already right. -->
  <meta name="color-scheme" content="light dark" />
  <link rel="stylesheet" href="/styles.css" />
</head>
MDN recommends the meta tag in the head, before any CSS, to help prevent a flash of the wrong colours while the page loads.[2]
CSS features for light and dark themes, what each does and its browser support according to MDN
FeatureWhat it doesBrowser support (MDN)
prefers-color-schemeWhat it doesMedia feature that tells CSS whether the visitor asked for a light or a dark theme. Its values are light and dark; no stated preference counts as light.Browser support (MDN)Widely available, across browsers since January 2020[1]
color-schemeWhat it doesProperty that says which schemes an element can be drawn in. The browser then matches the canvas, scrollbars and form controls.Browser support (MDN)Widely available, across browsers since January 2022[2]
<meta name="color-scheme">What it doesThe same statement for the whole document, readable before any CSS has loaded.Browser support (MDN)MDN gives it no separate date; it takes the values of color-scheme[3]
light-dark()What it doesFunction that takes two colours or two images and returns the one for the active scheme. Needs color-scheme: light dark.Browser support (MDN)Baseline 2024, newly available since May 2024[4]

Emulating dark mode in Playwright and Puppeteer

Playwright and Puppeteer both emulate the media query without touching the machine they run on. Playwright takes a colorScheme option with the values light, dark and no-preference, for a whole context or for one page.[10] Puppeteer takes a list of media features in page.emulateMediaFeatures.[11]

Both flip switch 1 only. For a site with its own theme button, click the button or set the class in the same script, before the screenshot.

Playwright and Puppeteer
// Playwright: for every page of a context
const context = await browser.newContext({ colorScheme: 'dark' })

// Playwright: on a page that is already open
await page.emulateMedia({ colorScheme: 'dark' })

// Puppeteer
await page.emulateMediaFeatures([
  { name: 'prefers-color-scheme', value: 'dark' },
])

Light and dark pairs of the same page

A light and dark pair is two screenshots of one page that differ in the theme and in nothing else. The work is in the second half of that sentence: anything else that moves between the two captures reads as a theme difference.

light.png
dark.png

When you want both

  • Documentation that shows each reader the screenshot matching their theme
  • App store and marketplace listings that present both looks
  • Design reviews, where the two themes are checked against each other
  • Release checks that a change did not break the theme nobody on the team uses

To show each reader the screenshot that matches their theme, put both files in a <picture> element, with the dark one in a <source media="(prefers-color-scheme: dark)">.[12]

Keep everything else the same

  1. Same window. A different width reflows the page and the two images no longer line up.

    viewport_width, viewport_height

  2. Same pixel density. The images must have the same pixel size to sit side by side.

    device_scale_factor

  3. Same scroll position. Capture both from the top, or both as full pages.

    full_page on both, or on neither

  4. Stopped animations. A carousel or a fade caught at two different moments looks like a theme difference.

    reduced_motion=true

  5. No overlays. A cookie banner that shows in one capture and not the other spoils the pair.

    block_cookie_banners=true

  6. Only the theme differs. Say light out loud as well, so both requests read the same.

    dark_mode=false, then dark_mode=true

One pair, two requests
SHOT="https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY\
&url=https://example.com\
&viewport_width=1280\
&viewport_height=800\
&device_scale_factor=2\
&reduced_motion=true\
&block_cookie_banners=true"

curl "$SHOT&dark_mode=false" --output light.png
curl "$SHOT&dark_mode=true"  --output dark.png

The option names are those of the CurlShot API. Any tool works, as long as both captures get the same settings.

What dark_mode does in a screenshot API

The dark_mode option of CurlShot is emulation of the media query, and nothing more. With dark_mode=true the browser that renders your page reports prefers-color-scheme: dark. With dark_mode=false, the default, it reports light, so you get the light theme even from a site that would go dark for some visitors.

It asks. It does not repaint. It does not force-darken a site that has no dark theme, and it cannot flip a theme that only changes with the site’s own button. There is also no option that writes localStorage before the page loads: a script you send runs on the loaded page, after the site has already read its storage.

For those sites, add one of the options in the table to the same request. The example sets the class that many sites use for their dark theme; the class or attribute of the site you capture is in its <html> tag after you press its theme button.

Try it without code on the dark mode screenshot page, or read dark mode and emulation and custom CSS, JavaScript and clicks in the docs.

A site whose theme is a class on <html>
curl -X POST "https://curlshot.com/api/v1/screenshot" \
  -H "X-Access-Key: YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "dark_mode": true,
    "scripts": "document.documentElement.classList.add(\"dark\")"
  }' \
  --output dark.png
click
Clicks the first element that matches a CSS selector.
Use it when: the site has a visible theme button. One click per request.
cookies
Sets cookies before the page loads.
Use it when: the site remembers the theme in a cookie and you know its name and value.
scripts
Runs your JavaScript on the loaded page, just before the capture.
Use it when: the theme is a class or attribute on <html>: set it directly.
styles
Adds your CSS on top of the site’s own.
Use it when: the site has no dark theme, or you need :root { color-scheme: dark; }.
wait_for_selector, delay
Hold the capture until an element is visible, or for a number of seconds.
Use it when: the theme arrives a moment after the first paint.

Dark mode glossary

Dark mode
A setting of a device or an app that asks for light text on dark backgrounds. A website shows a dark theme only if its authors wrote one.
Colour scheme
The pair of looks a page can have: light or dark. CSS uses the American spelling, color-scheme.
prefers-color-scheme
The CSS media feature that reports whether the visitor asked for a light or a dark theme, through the operating system or the browser.
color-scheme
The CSS property, and the meta tag of the same name, with which a page says which schemes it supports, so the browser draws its own parts to match.
light-dark()
A CSS function that holds a light value and a dark value and returns the one for the active colour scheme.
Theme toggle
A button on a site that switches its theme with a script and remembers the choice in localStorage or a cookie.
Emulation
A browser pretending to have a setting it does not have. Emulating a dark preference changes what the media query answers, and nothing else.
Forced dark
A browser darkening a page that has no dark theme, by generating one. Chrome calls its version Auto Dark Theme.
Flash of the wrong theme
The moment a page shows its default colours before a script applies the saved theme. A capture can land in it.

Questions people ask

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

Make the browser report a dark preference, then take the screenshot. By hand: switch the operating system to dark, or in Chrome DevTools open the Rendering tab and set "Emulate CSS media feature prefers-color-scheme" to dark. In code: colorScheme: 'dark' in Playwright, emulateMediaFeatures in Puppeteer, or dark_mode=true in a CurlShot request.

Why does a website ignore my dark mode setting?

Either the site has no dark theme, or its dark theme is switched by its own button and not by the prefers-color-scheme media query. In the second case the site sets a class or attribute on the html element with a script and remembers the choice in localStorage or a cookie, so the system setting is never asked.

Why is a site dark in my browser but light in a screenshot tool?

Because your browser remembers a choice you made on that site, in localStorage or a cookie, and a screenshot tool starts with empty storage like a first-time visitor. Send the cookie the site uses, press its theme button, or set the class on the html element with a script before the capture.

Can I force dark mode on a website that has no dark theme?

Not by emulation: a dark preference changes nothing on a site with no dark styles. Some browsers can generate a dark version by themselves (Chrome on Android calls it Auto Dark Theme), and you can add your own CSS before a capture, but the result is a repaint, not the site's design.

How do I screenshot a website in light mode when it defaults to dark?

Emulate the light preference: prefers-color-scheme: light in developer tools, or colorScheme: 'light' in Playwright. In CurlShot, dark_mode is false by default, so the rendering browser always reports light unless you ask for dark. A site whose only design is dark stays dark.

What is the difference between prefers-color-scheme and color-scheme?

prefers-color-scheme is a media feature: it lets the CSS of a page read what the visitor asked for. color-scheme is a property and a meta tag: it lets the page tell the browser which schemes it supports, so the browser draws form controls, scrollbars and the canvas to match. A complete dark theme uses both.

How do I make matching light and dark screenshots of the same page?

Capture twice with everything identical except the theme: the same viewport width and height, the same pixel density, the same scroll position or full page setting, animations stopped and overlays blocked. Then change only the colour scheme between the two captures.

Sources

  1. [1]MDN Web Docs, prefers-color-scheme. Checked .
  2. [2]MDN Web Docs, color-scheme. Checked .
  3. [3]MDN Web Docs, <meta name="color-scheme">. Checked .
  4. [4]MDN Web Docs, light-dark(). Checked .
  5. [5]Chrome for Developers, Auto Dark Theme. Checked .
  6. [6]Chrome for Developers, Emulate CSS media features. Checked .
  7. [7]Chrome for Developers, Rendering tab overview. Checked .
  8. [8]Firefox Source Docs, Examine and edit CSS. Checked .
  9. [9]WebKit, Web Inspector: Elements tab. Checked .
  10. [10]Playwright, Emulation. Checked .
  11. [11]Puppeteer, Page.emulateMediaFeatures() method. Checked .
  12. [12]web.dev, prefers-color-scheme: Hello darkness, my old friend. Checked .
  13. [13]Apple Support, Use a light or dark appearance on your Mac. Checked .
  14. [14]Apple Support, Use Dark Mode on your iPhone and iPad. Checked .
  15. [15]Microsoft Support, Change colors in Windows. Checked .
  16. [16]Android Help, Change to dark theme or adjust the color scheme on your Android device. Checked .

Screenshot any page in one step

Paste an address into CurlShot and download the screenshot. A free account gives you 100 screenshots every month. No card needed.