> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/tailwindlabs/tailwindcss/llms.txt > Use this file to discover all available pages before exploring further. # Dark Mode > Learn how to implement dark mode in your Tailwind projects using class-based, media query, or custom strategies. Tailwind includes a `dark` variant that lets you style your site differently when dark mode is enabled. ## Dark Mode Strategies Tailwind supports multiple strategies for implementing dark mode. Choose the one that best fits your project's needs. ### Media Query Strategy (Default) By default, Tailwind uses the `prefers-color-scheme` media query to detect dark mode: ```html theme={null}

Hello World

``` This generates CSS like: ```css theme={null} .bg-white { background-color: #fff; } @media (prefers-color-scheme: dark) { .dark\:bg-gray-900 { background-color: #111827; } } ``` From the source code, the media strategy is implemented as: ```typescript theme={null} if (mode === 'media') { addVariant('dark', '@media (prefers-color-scheme: dark)') } ``` ### Selector Strategy (Class-based) For manual dark mode toggling, use the selector strategy by adding a `dark` class to your HTML: ```css theme={null} @theme { --dark-mode: selector; } ``` Now dark mode is controlled by a `.dark` class on a parent element: ```html theme={null}
``` The selector strategy uses the `:where()` pseudo-class for specificity control: ```typescript theme={null} if (mode === 'selector') { addVariant('dark', `&:where(${selector}, ${selector} *)`) } ``` This generates CSS like: ```css theme={null} .bg-white { background-color: #fff; } .dark\:bg-gray-900:where(.dark, .dark *) { background-color: #111827; } ``` ### Custom Selector Customize the dark mode selector: ```css theme={null} @theme { --dark-mode: selector(.nightmode); } ``` ```html theme={null} ``` ### Variant Strategy For complete control, use the variant strategy with a custom selector pattern: ```css theme={null} @theme { --dark-mode: variant('[data-theme="dark"] &'); } ``` ```html theme={null}
``` When using the variant strategy, you must include `&` in your selector to indicate where the utility's selector should be inserted. ## Common Dark Mode Patterns ### Color Schemes ```html theme={null}

Heading

Body text

``` ```html theme={null}
Item 1
Item 2
``` ```html theme={null}
Card with adjusted shadow in dark mode
``` ### Form Elements ```html theme={null} ``` ### Images & Icons ```html theme={null} Logo ``` ### Gradients ```html theme={null}
Gradient that adapts to dark mode
``` ## Combining with Other Variants Dark mode works seamlessly with all other Tailwind variants: ### Hover States ```html theme={null} ``` ### Focus States ```html theme={null} ``` ### Responsive Design ```html theme={null}
Different colors per breakpoint and mode
``` ### Group Hover ```html theme={null}
Nested element responds to parent hover in both modes
``` ## Toggling Dark Mode When using the selector strategy, implement dark mode toggling with JavaScript: ```javascript Vanilla JS theme={null} // On page load or when changing themes, best to add inline in `head` to avoid FOUC if (localStorage.theme === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) { document.documentElement.classList.add('dark') } else { document.documentElement.classList.remove('dark') } // Whenever the user explicitly chooses light mode localStorage.theme = 'light' // Whenever the user explicitly chooses dark mode localStorage.theme = 'dark' // Whenever the user explicitly chooses to respect the OS preference localStorage.removeItem('theme') ``` ```javascript React theme={null} import { useState, useEffect } from 'react' function ThemeToggle() { const [darkMode, setDarkMode] = useState(false) useEffect(() => { const isDark = localStorage.theme === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches) setDarkMode(isDark) if (isDark) { document.documentElement.classList.add('dark') } }, []) const toggleDarkMode = () => { setDarkMode(!darkMode) if (!darkMode) { document.documentElement.classList.add('dark') localStorage.theme = 'dark' } else { document.documentElement.classList.remove('dark') localStorage.theme = 'light' } } return ( ) } ``` ```javascript Vue theme={null} ``` ## Avoiding Flash of Unstyled Content When using the selector strategy, add this script to your `` before any other content to prevent a flash of the wrong theme: ```html theme={null} ``` This script must run synchronously in the `` before your content renders. Don't defer or async it. ## Best Practices ### Design System Consistency Define semantic color variables that work in both modes: ```css theme={null} @theme { /* Light mode colors */ --color-background: white; --color-foreground: black; --color-primary: #3b82f6; /* Dark mode overrides */ @media (prefers-color-scheme: dark) { --color-background: #111827; --color-foreground: white; --color-primary: #60a5fa; } } ``` ### Accessibility Ensure sufficient contrast in both modes: ```html theme={null}
``` ### Test Both Modes Always test your UI in both light and dark modes to ensure: * Sufficient color contrast * Readable text * Visible borders and dividers * Proper image handling * Correct icon colors Use browser DevTools to toggle between light and dark mode preferences for quick testing.