How to Make Your Email Template Dark Mode Compatible

A practical guide to color-scheme meta tags, prefers-color-scheme CSS, Gmail's forced inversion, and image handling.

Akash Bhadange • 03 Jun, 2026 • how to guide

Dark mode is everywhere. Over 80% of smartphone users have it enabled. A significant chunk of your subscribers are reading your emails on a dark background right now.

The problem: most email templates are built for light mode. When dark mode kicks in, email clients either invert your colors automatically or apply their own interpretation. Your carefully chosen brand colors become something unrecognizable. White backgrounds turn gray or black. Dark text disappears. Logos with transparent backgrounds end up on the wrong color.

You can control most of this. Here is how.

How Dark Mode Works in Email Clients

Before writing a single line of CSS, it helps to understand what is actually happening.

Email clients handle dark mode in one of two ways:

Full support. The client respects your CSS and applies your dark mode styles when the user has dark mode enabled. Apple Mail, iOS Mail, Outlook for Mac, and Samsung Mail all fall into this category. You write the styles, they use them.

Forced inversion. The client ignores your CSS and applies its own dark mode transformation. Gmail on web and Android does this. It analyzes your email's background and text colors and tries to flip them intelligently. Sometimes it works well. Sometimes it turns your turquoise CTA button into a muddy green. You have limited control here, but there are techniques to reduce surprises.

No dark mode support. Some clients do not respond to dark mode at all. Windows Outlook is the main example. Your light mode design shows up regardless of the user's system settings.

Knowing which camp each client falls into tells you where to focus your energy.

Step 1: Declare That You Support Dark Mode

The first thing to do is tell email clients that your template is dark-mode-aware. Without this declaration, some clients assume you have not thought about it and take matters into their own hands.

Add these two meta tags inside your <head>:

<meta name="color-scheme" content="light dark" />
<meta name="supported-color-schemes" content="light dark" />

Then add the color-scheme property to your root CSS:

:root {
	color-scheme: light dark;
}

This is the handshake. You are telling the client: "I know about dark mode, and I have handled it." Clients that respect this declaration will let your CSS take over instead of applying their own forced transformations.

Step 2: Write Your Dark Mode Styles

Now write the actual dark mode overrides using the prefers-color-scheme media query.

@media (prefers-color-scheme: dark) {
	body {
		background-color: #1a1a1a !important;
		color: #e0e0e0 !important;
	}

	.email-container {
		background-color: #2d2d2d !important;
	}

	.email-body {
		color: #e0e0e0 !important;
	}

	a {
		color: #a8d8ff !important;
	}

	.cta-button {
		background-color: #4a9eff !important;
		color: #ffffff !important;
	}
}

A few things to keep in mind here.

You need !important on everything. Email templates use inline styles for compatibility reasons. Inline styles have higher specificity than stylesheet rules, so without !important, your dark mode overrides will lose to the inline styles every time.

Set colors explicitly on every element. If an element does not have a defined background color, dark mode transformations can produce unexpected results. Be explicit: every container, every text block, every button should have a defined color in both your base styles and your dark mode overrides.

Watch your link colors. The default blue (#0000ff or similar) often becomes unreadable on dark backgrounds. Always explicitly set link colors in your dark mode block.

Step 3: Handle Gmail's Forced Dark Mode

Gmail does not fully respect the prefers-color-scheme media query in the same way as Apple Mail. It applies its own dark mode class to your email's wrapper element. You can target this with the [data-ogsc] attribute selector.

[data-ogsc] body {
	background-color: #1a1a1a !important;
	color: #e0e0e0 !important;
}

[data-ogsc] .email-container {
	background-color: #2d2d2d !important;
}

[data-ogsc] .cta-button {
	background-color: #4a9eff !important;
	color: #ffffff !important;
}

Gmail injects data-ogsc on the outermost container when it is rendering in dark mode. Targeting it gives you a hook. You cannot get full control over Gmail's dark mode rendering, but this gets you closer.

One useful trick: use transparent backgrounds where possible instead of white. If you set background-color: transparent on elements that do not need a specific background, Gmail will choose an appropriate dark color rather than trying to invert white to something weird.

Step 4: Handle Images

Images are where dark mode gets tricky. A few strategies:

Use PNG with transparent backgrounds for logos and icons. If your logo has a white or light background baked in, it will look out of place on a dark email background. Export it with a transparent background so it sits naturally on whatever color the email client chooses.

Swap images for dark mode. If you need a specific dark version of an image, you can hide and show images conditionally using your dark mode media query:

<!-- Light mode image -->
<img class="light-logo" src="logo-light.png" alt="Company Logo" />

<!-- Dark mode image -->
<img
	class="dark-logo"
	src="logo-dark.png"
	alt="Company Logo"
	style="display: none;"
/>

@media (prefers-color-scheme: dark) {
	.light-logo {
		display: none !important;
	}
	.dark-logo {
		display: block !important;
	}
}

This gives you a completely different image in dark mode. Useful for logos, hero images, or any image where color matters.

Watch for photos with light backgrounds. A product photo with a white background will have a jarring white box around it in dark mode. Either use transparent PNGs, or add a subtle border or shadow to contain the image visually.

Step 5: Test Before You Send

Dark mode rendering varies enough across clients that you cannot just write the CSS and assume it works. You need to actually look at it.

Test in Apple Mail. Enable dark mode on your Mac or iPhone and send yourself the email. Apple Mail is the most faithful renderer and will show you exactly what your CSS does.

Test in Gmail. Open the email in Gmail on Android or in Chrome with dark mode enabled. This shows you what Gmail's forced dark mode does to your template.

Use a rendering tool. Litmus and Email on Acid both let you preview across 100+ clients without sending a real email. If you are sending to a large list, it is worth running your template through one of these before you hit send.

The two most common surprises people find during testing: buttons that change color unexpectedly, and sections where text becomes unreadable because both the text and background shifted to similar dark values. Catch these before your subscribers do.

Client Support Summary

Client	Dark Mode Support
Apple Mail (Mac + iOS)	Full — respects your CSS
iOS Mail	Full — respects your CSS
Outlook for Mac	Full — respects your CSS
Samsung Mail	Full — respects your CSS
Gmail (web + Android)	Partial — forced inversion, targetable with `[data-ogsc]`
Outlook for Windows	None — always renders light mode
Yahoo Mail	Partial — varies by version

A Quick Template Checklist

Before sending any email template, run through this:

color-scheme meta tags are in the <head>
All background colors are explicitly set on every container and section
All text colors are explicitly set
prefers-color-scheme: dark block with !important overrides is in the stylesheet
[data-ogsc] overrides are included for Gmail
Logos are exported as transparent PNG
Link colors are explicitly set in dark mode
CTA button colors are explicitly set in dark mode
Tested in Apple Mail dark mode
Tested in Gmail dark mode

The Bottom Line

Dark mode is not optional anymore. It is the default for a large portion of your audience.

The good news: the implementation is straightforward. A color-scheme declaration, a prefers-color-scheme media query block, [data-ogsc] targeting for Gmail, and transparent PNG assets covers the vast majority of cases.

The main risk is not doing it at all. An unhandled dark mode template can turn a polished, on-brand email into something that looks broken. That damages trust in a way that is hard to measure but easy to avoid.

Write the styles once. They carry forward into every template you build from it.

Still wondering?

See what your favorite LLM has to say about us,
then make an informed decision.

Ask ChatGPT

Ask Gemini

Ask Claude

Ask Perplexity

Talk to a Human