WordPress Development

Adding Dark Mode to a WordPress Theme the Right Way

Adding Dark Mode to a WordPress Theme the Right Way

Dark mode has gone from a novelty to an expectation. Operating systems, browsers and most major apps offer it, and many people set their devices to switch automatically in the evening. When they visit a website that blasts a bright white page at them at night, it feels jarring.

Adding dark mode to a WordPress theme isn’t difficult, but doing it well takes more thought than inverting colours. I’ve seen dark modes with unreadable grey-on-grey text, logos that disappear against dark backgrounds, images that look washed out and toggles that make the whole page flash white before switching.

Here’s how I approach dark mode in WordPress themes so it’s comfortable, accessible and reliable.

Decide what kind of dark mode you want

There are three common approaches:

  1. Automatic: follow the visitor’s system preference using the prefers-color-scheme media query. No toggle needed.
  2. Toggle only: offer a button so visitors can switch, ignoring the system setting.
  3. Automatic with override: follow the system preference by default, but let visitors override it with a toggle, and remember their choice.

The third option is the most user-friendly and what I usually build. Visitors get the mode their device prefers, but anyone who prefers something different can change it.

Start with colour tokens

The foundation of a good dark mode is defining colours by role, not by appearance. Instead of using “white” and “dark grey” throughout your CSS, define tokens like background, surface, text, muted text, border and accent. Then dark mode simply swaps the values of those tokens.

Every component uses these variables:

If your theme currently has colours hard-coded in many places, refactoring to tokens is the bulk of the work. It’s worth it, because it also makes future redesigns much easier.

Following the system preference

The prefers-color-scheme media query detects whether the visitor’s system is set to dark mode:

Also set the color-scheme property, which tells the browser to render built-in elements like form controls, scrollbars and default backgrounds in the appropriate mode:

Choosing dark mode colours

Good dark mode palettes follow a few principles:

  • Avoid pure black backgrounds. Very dark greys are easier on the eyes and allow subtle depth through slightly lighter surfaces.
  • Avoid pure white text. Slightly off-white text reduces glare on dark backgrounds.
  • Lighten and desaturate accent colours. A strong blue that works on white often looks too intense or too dark on a dark background. Use lighter, softer versions.
  • Use lighter surfaces for elevation. In dark mode, cards and menus that sit “above” the page are usually slightly lighter than the background, rather than using heavy shadows.
  • Check contrast. Dark mode still needs to meet contrast requirements: at least 4.5 to 1 for normal text. Muted text and borders are easy to make too faint.

Adding a toggle

To let visitors override the system preference, store their choice and apply it with a data attribute on the root element:

Then guard the system media query, so it only applies when the visitor hasn’t made an explicit choice:

Avoiding the flash

The biggest technical mistake with dark mode toggles is applying the stored preference too late. If the script runs after the page renders, visitors see a flash of the wrong theme every time they load a page.

The fix is a tiny inline script in the page head, before any content renders, that reads the stored preference and sets the attribute immediately:

if (t === 'dark't === 'light') {

The try and catch matters, because localStorage can be unavailable in some private browsing modes or restricted environments. If it fails, the system preference still works.

In WordPress, add this as early as possible in the head, for example with a wp_head action at a very early priority, or directly in your block theme’s header template part using wp_print_inline_script_tag.

The toggle button

Make the toggle accessible:

  • Use a real button element.
  • Give it a clear accessible name, like “Switch to dark mode”, and update it when the mode changes, or use aria-pressed to indicate the state.
  • Make it keyboard accessible with a visible focus style.
  • Don’t rely only on an icon; include a text label for screen readers.

Consider offering a third option, “use system setting”, for visitors who change their mind.

Dark mode in block themes

In block themes, colours are defined in theme.json. Style variations, alternative JSON files in the theme’s styles folder, can provide a dark palette that site owners select in the Site Editor. That’s useful when the site owner wants to choose a dark design for the whole site.

For visitor-controlled dark mode, the approach above still applies. Map your theme.json palette slugs to role-based names like base and contrast, then override the generated CSS variables for dark mode:

Because blocks use these variables, they switch automatically. Role-based slugs make this possible; slugs named after specific colours, like white or navy, make it confusing.

Be careful with colours editors choose manually in blocks. If an editor sets a paragraph background to a specific light colour, it won’t change in dark mode unless that colour comes from the palette. Restricting editors to the theme palette helps dark mode work consistently.

Handling images and media

Logos

A dark logo disappears on a dark background. Options include:

  • Providing a light version of the logo and switching it in dark mode.
  • Using an SVG logo that uses currentColor, so it inherits the text colour automatically.
  • Placing the logo on a light background badge in dark mode.

The picture element can serve a different image based on the colour scheme:

Note that this follows the system preference, not your toggle. For toggle support, switch images with CSS or JavaScript based on the data attribute.

Photos

Bright photos can feel harsh in dark mode. A subtle reduction in brightness can help, but be careful not to make important images look dull:

Diagrams and screenshots

Images with transparent backgrounds and dark lines, like diagrams, can become invisible on dark backgrounds. Give them a light background in dark mode, or provide dark-mode versions.

Embeds

Third-party embeds like maps, videos and social posts may not support dark mode. They’ll remain light, which is usually acceptable, but check they don’t look broken.

Forms and interactive elements

Check every interactive element in dark mode:

  • Form inputs, select menus and checkboxes.
  • Focus outlines, which need enough contrast against dark backgrounds.
  • Hover and active states.
  • Error and success messages.
  • Tables, code blocks and blockquotes.

The color-scheme property handles many native controls, but custom-styled elements need explicit dark styles.

Testing dark mode

  • Switch your operating system between light and dark and reload.
  • Use browser developer tools to emulate prefers-color-scheme.
  • Test the toggle, including after reloading and navigating between pages, to make sure there’s no flash.
  • Check contrast for text, links, borders and focus styles.
  • Review every template: home, posts, pages, archives, search, forms, cart and checkout.
  • Test with localStorage blocked, such as in some private browsing modes.

Keep dark mode maintainable

Dark mode doubles the number of colour combinations in your theme, so it can become hard to maintain if it isn’t organised. A few habits keep it under control. Define every colour as a token and never hard-code colour values in component styles. Keep the light and dark values for each token side by side in one place, so changing one reminds you to check the other. When you add a new component, test it in both modes before considering it finished. And document your palette, including which token to use for which purpose, so anyone working on the theme later follows the same system.

These habits turn dark mode from a fragile add-on into a natural part of the design system.

Frequently asked questions

Do I need a toggle if I follow the system setting?

Not strictly. Following the system preference alone is simple and respects user choice. A toggle helps visitors who want a different mode for your site than their system default.

Does dark mode affect SEO?

No. Search engines don’t rank sites based on colour scheme. Dark mode is purely about user experience.

Why does my page flash white before switching to dark mode?

The stored preference is applied too late. Add a small inline script in the head that sets the theme attribute before the page renders.

Can I add dark mode without editing theme files?

Some plugins add dark mode automatically, often by inverting colours. Results vary, and they rarely handle logos and images as well as a theme-level implementation.

Final thoughts

A good dark mode is more than inverted colours. Build your theme on role-based colour tokens, follow the system preference, add an accessible toggle that applies instantly without flashing, choose dark palettes that keep contrast strong, handle logos and images thoughtfully and test every template. Done well, dark mode makes your site comfortable to read at any hour, and visitors notice the care.