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.
Drag the line on the page, or use the slider. Same page, same layout: only the colours 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
Operating system
The visitor picks light or dark once, in the system settings.
- 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.
- 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
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 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.
- Switch 1Emulation flips it
The media query
The site’s CSS asks
prefers-color-schemeand 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.
- 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"ordata-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.
- 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.
| Symptom | Cause | Fix |
|---|---|---|
| The whole page stays lightLooks like: stays light | CauseThe 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 light | CauseYou 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 light | CauseThe 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 image | CauseA 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 logo | CauseA 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 controls | CauseThe 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 document | CauseA 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
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.
| Where | Path |
|---|---|
| Chrome DevTools | Rendering 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 DevTools | Page 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 Inspector | Elements 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.
| Where | Path |
|---|---|
| macOS | System Settings›Appearance›Light, Dark or Auto[13]Auto follows the Night Shift schedule. |
| Windows | Settings›Personalization›Colors›Choose your mode›Light, Dark or Custom[15] |
| iPhone and iPad | Settings›Appearance›Dark[14]In iOS 26 and earlier the options are under Settings > Display & Brightness. |
| Android | Settings›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.
: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);
}: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; }light-dark() holds both values and follows color-scheme, so a theme button only has to set the scheme.[4]<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>| Feature | What it does | Browser support (MDN) |
|---|---|---|
prefers-color-scheme | What 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-scheme | What 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: 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.
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
Same window. A different width reflows the page and the two images no longer line up.
viewport_width,viewport_heightSame pixel density. The images must have the same pixel size to sit side by side.
device_scale_factorSame scroll position. Capture both from the top, or both as full pages.
full_pageon both, or on neitherStopped animations. A carousel or a fade caught at two different moments looks like a theme difference.
reduced_motion=trueNo overlays. A cookie banner that shows in one capture and not the other spoils the pair.
block_cookie_banners=trueOnly the theme differs. Say light out loud as well, so both requests read the same.
dark_mode=false, thendark_mode=true
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.pngThe 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.
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]MDN Web Docs, prefers-color-scheme. Checked .
- [2]MDN Web Docs, color-scheme. Checked .
- [3]MDN Web Docs, <meta name="color-scheme">. Checked .
- [4]MDN Web Docs, light-dark(). Checked .
- [5]Chrome for Developers, Auto Dark Theme. Checked .
- [6]Chrome for Developers, Emulate CSS media features. Checked .
- [7]Chrome for Developers, Rendering tab overview. Checked .
- [8]Firefox Source Docs, Examine and edit CSS. Checked .
- [9]WebKit, Web Inspector: Elements tab. Checked .
- [10]Playwright, Emulation. Checked .
- [11]Puppeteer, Page.emulateMediaFeatures() method. Checked .
- [12]web.dev, prefers-color-scheme: Hello darkness, my old friend. Checked .
- [13]Apple Support, Use a light or dark appearance on your Mac. Checked .
- [14]Apple Support, Use Dark Mode on your iPhone and iPad. Checked .
- [15]Microsoft Support, Change colors in Windows. Checked .
- [16]Android Help, Change to dark theme or adjust the color scheme on your Android device. Checked .
Read next
- Field guideWhy website screenshots look wrong, and the fixesA field guide to 11 ways a website screenshot goes wrong, from blank lazy images to cookie banners and cut-off pages, with the cause and the fix for each.
- GuideVisual regression testing, explained in picturesHow screenshot comparison works, why visual tests go flaky and how to fix each cause, the tools, and a set-up checklist with a Playwright example.
- CalculatorScreenshot API vs headless browser: the real costA cost calculator with every assumption editable, the hidden work behind headless Chrome, and an honest checklist for build or buy.