How to Build Dark Mode with HTML, CSS, and JS: The Modern Way

Remember wrestling with those massive, hundreds-of-lines-long stylesheets just to make a theme toggle work? You’d find yourself chaining selectors like body.dark .card or body.dark .header across every single component until your eyes crossed. Honestly, if you're still building themes that way today, you’re burning precious energy on unnecessary, tedious grunt work.

Browser engines have matured quietly behind the scenes, and they’re finally equipped to shoulder the heavy lifting for us. We can safely retire those tangled selector hacks. I’m going to walk you through setting up an elegant dark mode where the browser does the theme-switching logic in virtually a single line of CSS via the modern light-dark() function, leaving JavaScript to handle what it actually belongs doing: remembering the user’s preference.

Along the way, we’ll assemble a slick, tactile animated switch and tuck the chosen state neatly into LocalStorage so it sticks across visits.

Grab a coffee, crack open your terminal, and let’s trim down that stylesheet.

Why the Old Way Just Doesn't Cut It Anymore

Think back to how we used to handle this: JavaScript slapped a .dark class onto the <body>, and then our CSS had to maintain two parallel realities. For every button, modal, or surface, you had to write overrides or maintain split sets of variables manually.

On anything larger than a toy project, that architecture fell apart fast. Introduce fifty color tokens, and congratulations - you just volunteered to write and audit fifty extra lines of override code across multiple files. With modern color-scheme support, you just tell the browser "Hey, I support both palettes," and hand the keys directly to your native custom properties.

Step 1: Laying Down the Markup and Toggle

We'll keep the DOM footprint lean, but we shouldn’t cut corners on the toggle switch itself - it's the linchpin of the whole user experience. Even if an OS preference is set, your visitors still deserve an effortless way to override it when the room lights change.

Drop this snippet wherever it makes sense in your layout (tucking it into your navigation or header bar usually feels most natural):

HTML

<div class="theme-switch-wrapper">
    <label class="theme-switch" for="darkModeToggle">
        <input type="checkbox" id="darkModeToggle" />
        <span class="slider">
            <i class="fas fa-sun sun-icon"></i>
            <i class="fas fa-moon moon-icon"></i>
        </span>
    </label>
</div>

The underlying mechanic is plain, bulletproof checkbox behavior: checked means dark mode, unchecked means light mode. Just make sure you’ve imported FontAwesome or whatever SVG icon set you lean on so the sun and moon render cleanly.

Step 2: The CSS Magic (light-dark())

Here’s where things get really fun. You don’t need @media (prefers-color-scheme) blocks scattered everywhere, nor do you need cascading theme classes. We register our intent right on :root.

Pay special attention to color-scheme: light dark; - that single declaration is your entry ticket. If you leave it out, the browser won't evaluate light-dark() at all.

CSS

:root {
    /* Tell the browser engine we understand both palettes natively */
    color-scheme: light dark;

    /* SYNTAX: light-dark(LIGHT_VAL, DARK_VAL);
       Both variants bundled right into one token!
    */
    
    /* Surface backgrounds */
    --bg-main: light-dark(#f0f4f8, #0b0d17);
    --bg-card: light-dark(#ffffff, #15192b);
    
    /* Typography */
    --text-primary: light-dark(#2d3748, #e2e8f0);
    --text-secondary: light-dark(#718096, #a0aec0);

    /* Brand accents (punchy blue by day, warm amber by night) */
    --accent-color: light-dark(#3182ce, #f6ad55);
    
    /* Toggle switch surfaces */
    --toggle-bg: light-dark(#cbd5e0, #2d3748);
    --toggle-active: var(--accent-color);
}

body {
    background-color: var(--bg-main);
    color: var(--text-primary);
    transition: background-color 0.4s ease, color 0.4s ease;
}

Look at how --bg-main works: you're casually telling the rendering engine, "When we're in light mode, paint it #f0f4f8; when night falls, swap to #0b0d17." Features like this show just how capable modern vanilla CSS has become without needing preprocessors or bloated runtime utilities.

Styling the Switch Mechanism

To give the toggle that satisfying hardware feel with subtle animations, drop in these styles:

CSS

.theme-switch-wrapper {
    display: flex;
    align-items: center;
    gap: 0.5rem;
}

.theme-switch {
    position: relative;
    display: inline-block;
    width: 60px;
    height: 30px;
}

.theme-switch input { opacity: 0; width: 0; height: 0; }

.slider {
    position: absolute;
    cursor: pointer;
    top: 0; left: 0; right: 0; bottom: 0;
    background-color: var(--toggle-bg);
    transition: 0.4s;
    border-radius: 30px;
    box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.1);
}

.slider:before {
    position: absolute;
    content: "";
    height: 22px; width: 22px;
    left: 4px; bottom: 4px;
    background-color: white;
    transition: 0.4s;
    border-radius: 50%;
}

input:checked + .slider { background-color: var(--toggle-active); }
input:checked + .slider:before { transform: translateX(30px); }

/* Icon Transitions */
.sun-icon, .moon-icon {
    position: absolute;
    top: 50%;
    transform: translateY(-50%);
    font-size: 0.875rem;
    transition: opacity 0.3s ease;
}
.sun-icon { left: 8px; color: #fbbf24; opacity: 1; }
.moon-icon { right: 8px; color: #f3f4f6; opacity: 0; }

input:checked ~ .slider .sun-icon { opacity: 0; }
input:checked ~ .slider .moon-icon { opacity: 1; }

Step 3: Wiring Up JavaScript and LocalStorage

At this point, your CSS is already responsive out of the box - flip your OS appearance right now, and the UI adapts automatically. But reality isn't always tied to the clock; someone sitting in a dim cafe might easily decide, "Give me dark mode right now, even if it’s noon."

The beauty here is that JS doesn't need to touch individual CSS classes. We simply nudge the root color-scheme property and commit the choice to localStorage. That way, when the visitor reloads or navigates around, their chosen environment is right where they left it.

JavaScript

const toggle = document.getElementById('darkModeToggle');
const root = document.documentElement;

// 1. Check storage when the page loads
const savedTheme = localStorage.getItem('theme-preference');

if (savedTheme) {
    // If a saved choice exists, let the engine know immediately
    root.style.colorScheme = savedTheme;
    
    // Sync the visual toggle state
    if (savedTheme === 'dark') {
        toggle.checked = true;
    }
}

// 2. Listen for clicks and update storage
toggle.addEventListener('change', function () {
    if (this.checked) {
        // User switched to Dark Mode
        root.style.colorScheme = 'dark';
        localStorage.setItem('theme-preference', 'dark');
    } else {
        // User switched to Light Mode
        root.style.colorScheme = 'light';
        localStorage.setItem('theme-preference', 'light');
    }
});

Under the hood, this keeps things remarkably fast. Because you're updating a single CSS property on the root rather than forcing DOM repaints across hundreds of class names, the transition stays silky smooth.

Your dashboard honors system defaults gracefully while leaving users in total control, all without polluting your codebase with duplicate rules. If you happen to be building this out inside a modern React setup, coupling it with Vite and Twin Macro is a great way to blend utility classes and CSS-in-JS without fighting styling collisions.

One quick tip if you're dropping this into a mobile-first layout: mobile browser chrome can be notoriously finicky with full-height headers. If you've ever dealt with layout jumps on phones, this breakdown on CSS vh, dvh, svh, and vw units explains exactly why classic 100vh stutters and which dynamic viewport unit will keep your sticky header perfectly anchored.