jvgomg · November 30, 2025 18:24
diff --git a/README.md b/README.md
diff --git a/theme-config.ts b/theme-config.ts
 /**
 * Theme configuration — single source of truth for theme colors.
 *
 * Used by both the viewport export (server-rendered meta tags) and
 * ThemeMetaSyncScript (client-side updates).
 */

 import { jade, jadeDark } from '@radix-ui/colors'
 import type { Viewport } from 'next'

 /** Maps theme names to their corresponding theme-color meta values. */
 export const themeColors: Record<string, string> = {
  light: jade.jade3,
  dark: jadeDark.jade2,
 }

 /**
 * Next.js viewport export with theme-color meta tags.
 *
 * Uses media queries to serve the correct color before JS loads.
 * Once hydrated, ThemeMetaSyncScript takes over and updates these
 * based on the user's actual theme selection.
 */
 export const viewport: Viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: themeColors.light },
    { media: '(prefers-color-scheme: dark)', color: themeColors.dark },
  ],
 }
diff --git a/theme-meta-sync.tsx b/theme-meta-sync.tsx
 /**
 * Keeps theme-color meta tags in sync with the active theme.
 *
 * next-themes sets `data-theme` on <html> but doesn't update theme-color meta
 * tags. This script observes `data-theme` changes and updates the meta tags
 * accordingly. It also watches <head> for mutations because Next.js App Router
 * replaces meta tags during navigation, which would otherwise overwrite our changes.
 *
 * Because we observe `data-theme` (managed by next-themes), this automatically
 * responds to OS theme changes when `enableSystem` is enabled on ThemeProvider.
 *
 * @see https://github.com/pacocoursey/next-themes/issues/78
 */

 import { themeColors } from './theme-config'

 function themeMetaSync(colors: Record<string, string>) {
  const updateThemeColor = () => {
    const activeTheme = document.documentElement.getAttribute('data-theme')
    if (!activeTheme) return

    const expectedColor = colors[activeTheme]
    if (!expectedColor) return

    const metaTags = document.querySelectorAll('meta[name="theme-color"]')
    if (!metaTags.length) return

    for (const metaTag of metaTags) {
      // Only update if different to avoid infinite loops
      if (metaTag.getAttribute('content') !== expectedColor) {
        metaTag.setAttribute('content', expectedColor)
      }
    }
  }

  // Observer 1: Watch for theme changes (user toggles theme)
  const themeObserver = new MutationObserver(updateThemeColor)
  themeObserver.observe(document.documentElement, {
    attributes: true,
    attributeFilter: ['data-theme'],
  })

  // Observer 2: Watch for <head> changes (Next.js navigation replaces meta tags)
  const headObserver = new MutationObserver(updateThemeColor)
  headObserver.observe(document.head, {
    childList: true,
    subtree: true,
  })

  // Initial sync on page load
  updateThemeColor()
 }

 export const ThemeMetaSyncScript = () => {
  return (
    <script
      dangerouslySetInnerHTML={{
        __html: `(${themeMetaSync.toString()})(${JSON.stringify(themeColors)})`,
      }}
    />
  )
 }
diff --git a/theme-provider.tsx b/theme-provider.tsx
 'use client'

 import { ThemeProvider as NextThemesProvider } from 'next-themes'

 export function ThemeProvider({ children }: { children: React.ReactNode }) {
  return (
    <NextThemesProvider
      attribute="data-theme"
      enableColorScheme
      enableSystem
      disableTransitionOnChange // this currently doesn't work (for my setup at least)
    >
      {children}
    </NextThemesProvider>
  )
 }
diff --git a/theme-state.ts b/theme-state.ts
 'use client'

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

 /**
 * Custom hook that wraps next-themes with a specific toggle behavior:
 * - First toggle: Override system preference to the opposite theme
 * - Second toggle: Return to system preference
 *
 * This creates a natural "try the other theme, then go back" experience,
 * and avoids persisting a theme override in localStorage when the user
 * ends up matching their system preference anyway.
 */
 export function useThemeState() {
  const { resolvedTheme, setTheme, systemTheme } = useTheme()
  const [mounted, setMounted] = useState(false)

  // Avoid hydration mismatch
  // eslint-disable-next-line react-hooks/set-state-in-effect
  useEffect(() => setMounted(true), [])

  const isDark = resolvedTheme === 'dark'

  const toggle = () => {
    if (systemTheme === resolvedTheme) {
      // Override to the opposite of system preference
      setTheme(isDark ? 'light' : 'dark')
    } else {
      // Return to system preference
      setTheme('system')
    }
  }

  return { mounted, isDark, toggle }
 }
File	Purpose
`theme-config.ts`	Theme colors and Next.js viewport export
`theme-state.ts`	`useThemeState` hook wrapping `next-themes`
`theme-meta-sync.tsx`	Inline script keeping meta tags in sync
	/**
	* Theme configuration — single source of truth for theme colors.
	*
	* Used by both the viewport export (server-rendered meta tags) and
	* ThemeMetaSyncScript (client-side updates).
	*/

	import { jade, jadeDark } from '@radix-ui/colors'
	import type { Viewport } from 'next'

	/** Maps theme names to their corresponding theme-color meta values. */
	export const themeColors: Record<string, string> = {
	light: jade.jade3,
	dark: jadeDark.jade2,
	}

	/**
	* Next.js viewport export with theme-color meta tags.
	*
	* Uses media queries to serve the correct color before JS loads.
	* Once hydrated, ThemeMetaSyncScript takes over and updates these
	* based on the user's actual theme selection.
	*/
	export const viewport: Viewport = {
	themeColor: [
	{ media: '(prefers-color-scheme: light)', color: themeColors.light },
	{ media: '(prefers-color-scheme: dark)', color: themeColors.dark },
	],
	}
	/**
	* Keeps theme-color meta tags in sync with the active theme.
	*
	* next-themes sets `data-theme` on <html> but doesn't update theme-color meta
	* tags. This script observes `data-theme` changes and updates the meta tags
	* accordingly. It also watches <head> for mutations because Next.js App Router
	* replaces meta tags during navigation, which would otherwise overwrite our changes.
	*
	* Because we observe `data-theme` (managed by next-themes), this automatically
	* responds to OS theme changes when `enableSystem` is enabled on ThemeProvider.
	*
	* @see https://github.com/pacocoursey/next-themes/issues/78
	*/

	import { themeColors } from './theme-config'

	function themeMetaSync(colors: Record<string, string>) {
	const updateThemeColor = () => {
	const activeTheme = document.documentElement.getAttribute('data-theme')
	if (!activeTheme) return

	const expectedColor = colors[activeTheme]
	if (!expectedColor) return

	const metaTags = document.querySelectorAll('meta[name="theme-color"]')
	if (!metaTags.length) return

	for (const metaTag of metaTags) {
	// Only update if different to avoid infinite loops
	if (metaTag.getAttribute('content') !== expectedColor) {
	metaTag.setAttribute('content', expectedColor)
	}
	}
	}

	// Observer 1: Watch for theme changes (user toggles theme)
	const themeObserver = new MutationObserver(updateThemeColor)
	themeObserver.observe(document.documentElement, {
	attributes: true,
	attributeFilter: ['data-theme'],
	})

	// Observer 2: Watch for <head> changes (Next.js navigation replaces meta tags)
	const headObserver = new MutationObserver(updateThemeColor)
	headObserver.observe(document.head, {
	childList: true,
	subtree: true,
	})

	// Initial sync on page load
	updateThemeColor()
	}

	export const ThemeMetaSyncScript = () => {
	return (
	<script
	dangerouslySetInnerHTML={{
	__html: `(${themeMetaSync.toString()})(${JSON.stringify(themeColors)})`,
	}}
	/>
	)
	}
	'use client'

	import { ThemeProvider as NextThemesProvider } from 'next-themes'

	export function ThemeProvider({ children }: { children: React.ReactNode }) {
	return (
	<NextThemesProvider
	attribute="data-theme"
	enableColorScheme
	enableSystem
	disableTransitionOnChange // this currently doesn't work (for my setup at least)
	>
	{children}
	</NextThemesProvider>
	)
	}
	'use client'

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

	/**
	* Custom hook that wraps next-themes with a specific toggle behavior:
	* - First toggle: Override system preference to the opposite theme
	* - Second toggle: Return to system preference
	*
	* This creates a natural "try the other theme, then go back" experience,
	* and avoids persisting a theme override in localStorage when the user
	* ends up matching their system preference anyway.
	*/
	export function useThemeState() {
	const { resolvedTheme, setTheme, systemTheme } = useTheme()
	const [mounted, setMounted] = useState(false)

	// Avoid hydration mismatch
	// eslint-disable-next-line react-hooks/set-state-in-effect
	useEffect(() => setMounted(true), [])

	const isDark = resolvedTheme === 'dark'

	const toggle = () => {
	if (systemTheme === resolvedTheme) {
	// Override to the opposite of system preference
	setTheme(isDark ? 'light' : 'dark')
	} else {
	// Return to system preference
	setTheme('system')
	}
	}

	return { mounted, isDark, toggle }
	}