Tailwind CSS darkMode strategy lacks built-in persistence for user theme selection

Why the default options fall short

Tailwind’s darkMode can be set to media or class. Neither of those knobs stores a user’s choice. With media the OS preference is respected, but a manual toggle must be re‑applied on every page load. With class the dark class is only present when you add it yourself; the class disappears on a hard refresh because the state is lost.

Recommended pattern for a smooth, persistent theme

1. Choose the class strategy. In tailwind.config.js set:

   module.exports = {
     darkMode: 'class',
     // …other config
   }
   

2. Persist the choice. Store the user’s preference in a cookie (visible to the server) or in localStorage (client‑only). Using a cookie guarantees the server can render the correct class on the first request.
3. Apply the class before CSS loads. Add a tiny inline script in the <head> that runs as early as possible:

   <script>
     (function () {
       const theme = document.cookie.match(/theme=([^;]+)/) ? RegExp.$1 : localStorage.getItem('theme');
       if (theme === 'dark') {
         document.documentElement.classList.add('dark');
       }
     })();
   </script>
   

   Because this script executes before the Tailwind CSS file is parsed, the browser will apply the correct styles immediately, eliminating the flash of the wrong theme.

4. Server‑side support. In your SSR template, read the theme cookie from the request and render <html class="dark"> when appropriate. If the cookie is missing, render the default <html>.
5. Toggle button. When the user changes the theme, update the cookie and localStorage and toggle the dark class on document.documentElement. Optionally trigger a full page reload to ensure server‑side rendering stays in sync.

Can a custom darkMode function read localStorage or a cookie?

No. A darkMode function in tailwind.config.js runs at build time, not at runtime. It has no access to the browser’s localStorage or to cookies that arrive with the HTTP request. Therefore it cannot be used to decide whether the dark class should be applied on the first paint.

Key take‑aways

• Use class mode and apply the dark class via an early inline script or server‑side cookie logic.
• Keep the inline script tiny to avoid blocking rendering and ensure it is allowed by your CSP (use a nonce if needed).
• Server‑side rendering benefits from a cookie so the initial HTML already contains the correct class.
• Custom darkMode functions cannot help with runtime persistence.

Do you currently store the theme in a cookie that is sent with the initial request, or only in localStorage?