Night mode is one of those features that sounds simple on the surface — just make the site dark — and turns out to be surprisingly nuanced the moment you start thinking about it seriously. What exactly does “smart” mean when it comes to night mode? How do you handle the white flash that ruins the experience? What happens to your images? What about pages with custom visual designs where dark mode looks wrong? What do you tell the user’s browser versus what you let the user decide for themselves?
This guide answers all of those questions from the ground up. It is written for WordPress site owners and developers who want to understand the full picture — not just follow a set of steps blindly, but genuinely understand why those steps matter, what the alternatives are, and what happens when you skip them. Whether you are setting up night mode for the first time or troubleshooting an existing implementation that is not behaving the way you expect, everything you need is here.
We walk through the entire process using Nexu Eclipse — the WordPress night mode plugin built specifically for smart, flash-free dark mode — as the reference implementation, because it handles the technical details correctly by design and makes the configuration options legible to non-developers. The concepts and principles apply regardless of what solution you use.
What “smart” night mode actually means
The word “smart” gets used loosely in plugin marketing, but when it comes to night mode it has a specific technical meaning. A smart night mode system is one that makes intelligent decisions automatically, without requiring user intervention for the most common scenarios, while still giving users control when they want it.
A basic night mode toggle does one thing: it switches the site between light and dark when a button is pressed. That is the starting point, not the destination. A smart implementation builds on that foundation with three additional capabilities that turn a basic toggle into a genuinely user-respecting experience.
Modern operating systems — macOS, Windows 11, iOS, Android — all expose a color scheme preference that websites can detect via the CSS media query prefers-color-scheme. This query is part of the W3C Media Queries Level 5 specification, which defines how browsers should expose user environment preferences to CSS. A smart night mode reads this preference and applies the appropriate theme automatically, before the user ever touches a toggle. If a visitor’s phone is in dark mode because they turned it on system-wide, they should not have to manually activate dark mode on every website they visit. Their preference is already expressed; a smart night mode respects it.
Not everyone wants every website to follow their OS preference. A user might have their phone in dark mode for system apps but prefer to read your blog in light mode because of its photography. Or vice versa — their OS is in light mode but your site at night feels too bright. The toggle exists specifically to let users express a preference for your site that differs from their system-wide setting. This is the override layer, and it sits on top of the OS detection layer.
Once a user sets a preference on your site, they should never have to set it again. The choice needs to be stored — in a cookie or localStorage — and re-applied on every subsequent visit and every page navigation. This is the layer where FOUC becomes critically important: if the stored preference is applied late, via JavaScript after page render, the user sees the wrong mode briefly before the stored choice kicks in. A smart night mode stores and applies the preference in a way that is present from the very first byte of every page.
A toggle that saves your choice to localStorage and re-applies it on page load is what the majority of free WordPress night mode plugins provide. It looks like a complete solution until you notice the flash, or until a first-time visitor with OS dark mode enabled gets the light version of your site because their preference was never detected. Layers 1 and 3 — OS detection and flash-free preference application — are where most implementations fall short, and where the quality gap between plugins becomes visible in practice.
Understanding FOUC: why the flash happens and how to fix it
Before you set up night mode, it is worth spending a moment understanding the flash problem properly, because the way you configure night mode — which plugin you use, which settings you apply — determines whether it exists at all on your site.
Browsers work in a specific sequence. They receive HTML, begin parsing it, apply CSS as they encounter it, and render pixels to the screen as early as possible. JavaScript, by contrast, executes after the HTML and CSS have been processed. For performance reasons, most JavaScript frameworks and practices encourage deferring script execution until the page is ready — which means after it has already been painted.
Night mode plugins that apply the dark class via JavaScript inherit this timing problem. The sequence is: page renders in light mode, JavaScript reads stored preference, JavaScript applies dark class, page snaps to dark. That snap — the white-to-dark transition that happens mid-render — is FOUC. On fast connections with modern hardware, it takes only a fraction of a second. On slower connections or older devices, it can take long enough to be genuinely disruptive.
There are two correct ways to eliminate it. The first is to use the native CSS prefers-color-scheme media query, which is evaluated entirely in CSS before any JavaScript runs. Users whose OS is in dark mode get dark styles from the first painted pixel because the CSS already knows what to apply. No JavaScript involved, no timing gap, no flash. This handles Layer 1 correctly.
The second is for Layer 3 — stored user preferences. Since CSS cannot read a cookie or localStorage value, the preference application requires a script. But that script must run synchronously, before the browser’s first paint, placed in the <head> as a render-blocking inline script rather than a deferred or asynchronous external file. This is normally bad practice for performance because render-blocking scripts delay page display. But for this specific use case — applying a stored visual preference — it is correct. The alternative is a flash on every page load for users who have expressed a preference.
A render-blocking inline script that reads a cookie and applies a class adds roughly 0.5 to 2 milliseconds to Time to First Byte on most modern hardware. The FOUC it prevents is visible for 50 to 300 milliseconds on the same hardware. The tradeoff is clear: the performance cost of preventing FOUC is an order of magnitude smaller than the visual disruption it prevents. Google’s own web.dev guide on prefers-color-scheme recommends the synchronous inline script approach for exactly this reason. Nexu Eclipse’s FOUC-free WordPress night mode implementation makes this tradeoff correctly by default — you do not need to configure it manually.
Step-by-step setup: installing and configuring smart night mode
With the theory in place, here is the practical setup process. Each step builds on the last, so working through them in order produces a fully configured and correctly behaving night mode experience on your WordPress site.
Before installing any night mode plugin, check your active plugins list for any existing dark mode implementations. Running two plugins that both modify page colors will produce conflicts ranging from incorrect colors to FOUC caused by competing class applications. If you have a previous dark mode plugin, deactivate and delete it before proceeding. Install Nexu Eclipse from the WordPress plugin repository or upload the premium version directly, then activate it. At this stage, the plugin is active but not yet configured — do not skip the configuration steps below.
Open the plugin settings panel and start with General. The first decision is the default mode: should new visitors see light mode or dark mode by default, before they have set any preference? For most sites, light mode as default with OS override enabled is the correct starting point — it respects the OS preference for users who have expressed one, and gives everyone else the conventional light experience. Enable “Sync with OS preference” so that prefers-color-scheme detection is active. This is your Layer 1 implementation.
Move to the Colors settings. This is where most of the visual work happens, and where most night mode setups either look professional or look like an afterthought. You need to define values for at least four element types: page background, primary text, secondary or muted text, and links. Think of each as a specific design decision. Your background should be dark but not pure black — pure black can feel harsh and creates excessive contrast with light text. A dark grey in the range of #1a1a1a to #2d2d2d reads as intentionally dark without the harshness. Your primary text should be off-white rather than pure white for the same reason. Links should use a lighter, accessible version of your brand accent color. Secondary text should be visibly dimmer than primary text, maintaining the hierarchy that exists in light mode.
#1e1e1e— warm dark grey
#e8e8e8— soft white
#a0a0a0— muted grey
#333333— subtle separator
These are a neutral starting point. Adjust the background toward cooler greys for a tech-forward feel or warmer greys for editorial and lifestyle sites. Your brand’s accent color should inform the link color choice.
Move to the Exclusions settings. This is the step most tutorials skip, and it is where night mode most often looks broken on real sites. The core exclusions to configure from the start are images and media. Unless your plugin handles this automatically, images in night mode will be processed along with everything else — potentially appearing tinted or with altered contrast. Add your logo to the exclusions by its CSS selector or element class. If you have custom hero sections with their own dark backgrounds, or infographics and charts that rely on specific color coding, exclude them here. The rule of thumb is: exclude anything whose appearance in dark mode is controlled by its own design rather than your site’s general palette.
The toggle is the visible face of your night mode system and should feel like part of your site’s design, not an afterthought. Consider where your visitors’ eyes naturally go: a toggle in the header near the navigation is the most discoverable. A fixed floating button in the corner is always visible but competes with other UI for attention. Icon-only toggles save space; labeled toggles (“Light / Dark”) reduce ambiguity for first-time users. Choose a style that matches your site’s visual weight — a minimal, icon-only moon/sun icon suits editorial sites, while a clearly labeled switch suits functional sites where clarity matters more than restraint.
After completing the configuration, test the result methodically. Open your site in an incognito window on a device with OS dark mode enabled — you should get the dark version without touching the toggle. Click the toggle — the switch should happen smoothly with no flash. Navigate to several pages — each navigation should load in the correct mode with no white flash between pages. Open the site in OS light mode with no stored preference — you should get light mode. Then switch via toggle, close the browser, reopen — your stored preference should persist. If you notice any flash during this testing, check whether any caching plugin is interfering with the head-injected script.
Advanced configuration: the settings that separate good from excellent
Once the core night mode is working correctly, there is a layer of advanced configuration that takes the experience from functional to genuinely polished. These settings are not required for a working night mode, but they are what make the difference between a setup that works and one that feels considered.
When a user clicks the toggle, the page should transition between modes smoothly rather than snapping instantly. A CSS transition of 200 to 350 milliseconds on color properties creates a pleasant fade that signals the change is deliberate. Too slow (above 500ms) and the transition feels sluggish — the user wonders if their click registered. Too fast (below 100ms) and the transition is barely perceptible, losing the feel of intentional design. The sweet spot is a quick but smooth fade that confirms the action without demanding the user’s attention.
Some implementations support time-based scheduling that automatically switches your site to dark mode at sunset in the user’s timezone and back to light mode at sunrise. This is the contextually ideal behavior — night mode activates exactly when conditions make it most useful and deactivates when it is no longer needed. Users who have not expressed a preference and have their OS on automatic get the same experience without any configuration on their part. This feature is not universally supported in all plugins, but when it is available, it is the most natural-feeling implementation of automatic dark mode.
Sometimes dark mode does not belong on specific pages at all — not because of individual elements, but because the entire page was designed with a dark or high-contrast aesthetic that does not benefit from, or actively conflicts with, additional night mode processing. Sales pages with dramatic gradient backgrounds, coming-soon pages with full-screen imagery, or login pages with specific visual branding can all fall into this category. Page-level exclusion lets you exclude an entire URL or URL pattern from night mode transformation, leaving the page exactly as designed while night mode continues to work everywhere else.
What the result looks like: light versus dark in practice
After completing the configuration, the before-and-after comparison tells the real story. The visual result should not look like a filter applied on top of your existing design — it should look like a deliberately designed alternative theme that shares your site’s structure and hierarchy while being completely comfortable to read in a dark environment.
Common problems after setup and how to diagnose them
Even with a well-configured plugin, a handful of issues can appear after setup. Most of them have straightforward causes.
The most common cause is a caching plugin that is serving cached versions of your pages with the inline head script stripped out or modified. Some aggressive caching configurations remove inline scripts from the document head for “performance.” Check your caching plugin’s settings for options that modify HTML head content, and either whitelist the night mode initialization script or disable that specific optimization. WP Rocket, W3 Total Cache, and LiteSpeed Cache all have settings that can affect inline script execution.
This happens when images are not excluded from the color transformations applied in dark mode. Go to your exclusions settings and verify that images are in the excluded elements list. If your images are wrapped in specific containers with custom classes rather than standard HTML img tags, you may need to add those container selectors to the exclusions list in addition to the img element itself.
If the stored preference is lost when the user closes and reopens the browser, check whether the plugin is using sessionStorage (which clears on browser close) rather than localStorage or a persistent cookie. This is a plugin architecture issue rather than a configuration problem. If you are using the correct plugin and still seeing this, check whether your cookie consent tool is blocking the night mode preference cookie from being set until the user accepts cookies — which creates a scenario where the preference can never persist for new visitors.
This is typically an exclusion issue rather than a color configuration issue. Identify the CSS selector for the problematic section using your browser’s developer tools, then add that selector to your exclusions list. If the section has a background color set inline via the WordPress block editor or a page builder, that inline style may be conflicting with the dark mode color override. Inline styles have higher specificity than plugin-applied CSS, so the conflict resolution depends on how your plugin handles specificity — check whether the plugin has a “force override” option for inline styles.
The complete setup checklist
Use this checklist to verify your night mode implementation is complete and correct. Each item maps to a specific aspect of a properly working smart night mode system.
A night mode that passes every item on that checklist is genuinely smart — it serves users who set OS preferences, serves users who want per-site control, remembers their choices without requiring repetition, looks visually coherent across the whole site, and degrades gracefully in the edge cases where dark mode processing does not apply. That is the complete picture, and it is what Nexu Eclipse — the complete smart WordPress night mode solution is built to deliver out of the box, with the configuration settings that let you tune it precisely to your site’s needs.
Everything in this guide, ready to use out of the box
Nexu Eclipse implements all three layers of smart night mode correctly: OS detection via CSS, flash-free preference storage, and a complete configuration system for colors, exclusions, toggle design, transitions, and scheduling.
Bought this guide hoping it'd fix my site's dark mode problems, but nope still getting that annoying white flash when pages load. And the "smart" toggle? Doesn't even remember my preference after I leave. total letdown
Finally a guide that actually explains it right.
This guide just saved me hours of trial and error. as a dev, I really appreciated how it actually explained why certain CSS properties behave differently in dark mode instead of just handing me a copy paste solution
Finally got around to setting up night mode on my WordPress site using this guide, and the part about handling that annoying white flash was a lifesaver. No more jarring bright screen before the dark theme kicks in. The toggle works instantly now, which is exactly what I wanted for my visitors.