diff --git a/ui/litellm-dashboard/src/app/layout.tsx b/ui/litellm-dashboard/src/app/layout.tsx
index a4ed17cde39..1ad2ef18c62 100644
--- a/ui/litellm-dashboard/src/app/layout.tsx
+++ b/ui/litellm-dashboard/src/app/layout.tsx
@@ -13,6 +13,20 @@ export const metadata: Metadata = {
icons: { icon: "./favicon.ico" },
};
+// Sets the `dark` class on synchronously before React hydrates, so
+// returning dark-mode users don't see a flash of light theme on page load.
+const darkModeInitScript = `
+(function () {
+ try {
+ var stored = window.localStorage.getItem('litellm-dark-mode');
+ if (stored === 'true') {
+ document.documentElement.classList.add('dark');
+ document.documentElement.style.colorScheme = 'dark';
+ }
+ } catch (e) {}
+})();
+`;
+
export default function RootLayout({
children,
}: Readonly<{
@@ -20,6 +34,9 @@ export default function RootLayout({
}>) {
return (
+
+
+
{children}
diff --git a/ui/litellm-dashboard/src/contexts/ThemeContext.tsx b/ui/litellm-dashboard/src/contexts/ThemeContext.tsx
index 058e98ad6f4..75df32e7eeb 100644
--- a/ui/litellm-dashboard/src/contexts/ThemeContext.tsx
+++ b/ui/litellm-dashboard/src/contexts/ThemeContext.tsx
@@ -44,14 +44,18 @@ export const ThemeProvider: React.FC = ({ children, accessTo
const [logoUrl, setLogoUrl] = useState(null);
const [faviconUrl, setFaviconUrl] = useState(null);
const [isDarkMode, setIsDarkModeState] = useState(false);
+ const [hydrated, setHydrated] = useState(false);
- // Hydrate dark mode from localStorage after mount to avoid SSR mismatch.
+ // Hydrate state from the value the inline init script already applied
+ // (see `darkModeInitScript` in app/layout.tsx). Until this runs we leave
+ // the DOM untouched so the SSR'd class set by the script survives.
useEffect(() => {
setIsDarkModeState(readInitialDarkMode());
+ setHydrated(true);
}, []);
useEffect(() => {
- if (typeof document === "undefined") return;
+ if (!hydrated || typeof document === "undefined") return;
const root = document.documentElement;
if (isDarkMode) {
root.classList.add("dark");
@@ -65,7 +69,7 @@ export const ThemeProvider: React.FC = ({ children, accessTo
} catch {
// ignore localStorage write errors
}
- }, [isDarkMode]);
+ }, [isDarkMode, hydrated]);
const setIsDarkMode = useCallback((value: boolean) => {
setIsDarkModeState(value);