Dark mode con next-themes

Risposta breve: avvolgi l'app in ThemeProvider con attribute="class", defaultTheme="system" e enableSystem, aggiungi @custom-variant dark al CSS di Tailwind 4 e leggi resolvedTheme nel toggle. next-themes applica la classe prima del primo paint.

Il provider, una volta sola

Il provider va montato sopra ogni cosa che legge il tema. Con l'App Router il file che lo contiene è un client component, richiamato dal layout server. disableTransitionOnChange disattiva le transizioni CSS durante il cambio, altrimenti il colore di sfondo si anima mentre la pagina cambia e il risultato sembra un glitch.

// app/providers.tsx
"use client";

import { ThemeProvider } from "next-themes";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    
      {children}
    
  );
}

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    
      
        {children}
      
    
  );
}

suppressHydrationWarning serve perché il server non può sapere quale tema ha scelto l'utente: la classe sull'elemento html cambia prima che React idrati, e senza l'attributo la console segnala un mismatch. Non è un permesso generale: vale solo per quell'elemento.

Tailwind 4 non legge .dark da solo

In Tailwind 4 la variante dark: segue di default prefers-color-scheme. Con next-themes la scelta è una classe, quindi la variante va ridefinita nel CSS globale. Senza questa riga il pulsante cambia la classe sull'html e nessuna utility dark: si attiva.

@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

I valori dei token per i due temi stanno in :root e .dark, con la mappatura in @theme inline. La procedura completa è in come tematizzare shadcn/ui.

Il toggle che non salta

Il tema salvato vive in localStorage, che il server non vede. Il primo render del client deve quindi mostrare qualcosa di neutro, e solo dopo l'idratazione può leggere il valore vero. resolvedTheme risolve «system» nella preferenza effettiva; theme può valere «system» e rompere un confronto con «dark».

"use client";

import { useEffect, useState } from "react";
import { useTheme } from "next-themes";

export function ThemeToggle() {
  const { resolvedTheme, setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);

  useEffect(() => setMounted(true), []);

  if (!mounted) {
    return ;
  }

  const isDark = resolvedTheme === "dark";

  return (
     setTheme(isDark ? "light" : "dark")}
    >
      {isDark ? "Chiaro" : "Scuro"}
    
  );
}

Perché non c'è il flash

next-themes inserisce uno script inline nel che legge localStorage e applica la classe prima che il browser dipinga il body. È lo stesso principio descritto in dark mode senza flash, con una differenza: qui lo script lo genera la libreria, quindi non va copiato a mano. Se il flash compare lo stesso, il provider è montato troppo in basso nell'albero o manca suppressHydrationWarning.

Limite dichiarato

Il tema cambia solo ciò che legge i token. Un componente con colori fissi, per esempio bg-white o text-zinc-900, resta chiaro anche in .dark: next-themes non riscrive le classi. Il catalogo, misurato il 1 novembre 2026, ha un solo blocco con «dark» nell'id, quindi la maggior parte degli esempi va verificata a mano nel tema scuro.

Dove continuare

Nel catalogo trovi la libreria shadcn, il record delle icone shadcn e un blocco con variante scura. Per il resto leggi che cosa è shadcn/ui e dark mode senza un secondo design system; il confronto tra strategie è in temi shadcn gratis o premium.