Theme Toggle

import { ThemeToggle } from '@youj/react'

<ThemeToggle />
<ThemeToggle variant="segmented" />

#Next.js App Router

For the whole setup in one place, ThemeScript with a ThemeToggle, see Light, dark and system in Next.js. The rest of this section is the next-themes route.

next-themes is the usual owner in Next.js. Install it (pnpm add next-themes, or npm install, yarn add, bun add), let it write data-theme, and hand the toggle its theme and setTheme. next-themes sets the attribute from an inline script before the page paints, so there's no flash of the other theme. suppressHydrationWarning on <html> covers the one attribute the server couldn't know. This is the same setup as Installation.

import { basalt, YoujProvider, themeProps } from '@youj/core'
import { ThemeProvider } from 'next-themes'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    // next-themes writes data-theme before the page paints; suppressHydrationWarning covers that one attribute.
    <html lang="en" suppressHydrationWarning {...themeProps(basalt)}>
      <body>
        <ThemeProvider attribute="data-theme" defaultTheme="system" enableSystem>
          <YoujProvider theme={basalt}>{children}</YoujProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}

'use client'

import { useTheme } from 'next-themes'
import { ThemeToggle } from '@youj/react'

export function ThemeSwitch() {
  const { theme, setTheme } = useTheme()
  return <ThemeToggle value={theme} onValueChange={setTheme} />
}

defaultTheme="system" follows the operating system until someone chooses; use "dark" for a dark-first app and keep enableSystem so System stays a choice.

On the server theme is undefined, but on the client's first render next-themes already returns the stored choice (or defaultTheme). So the toggle ignores value until it has mounted: the server markup and the hydrating render agree, with no mismatch and no mounted guard of your own. Until then the button draws the sun or the moon from the data-theme next-themes has already set, in the same box, so the icon doesn't flash or shift when the toggle takes over. The segmented variant shows its choice once mounted.

#Without next-themes

An uncontrolled ThemeToggle needs the same early script. Render ThemeScript in <head>. It sets data-theme and color-scheme from the stored choice before the page paints, so <html> needs suppressHydrationWarning too, or React reports the attributes the server couldn't know. npx @youj/cli init writes both in a Next.js or React Router app; add them by hand otherwise.

import { basalt, themeProps } from '@youj/core'
import { ThemeScript } from '@youj/react'

<html lang="en" suppressHydrationWarning {...themeProps(basalt)}>
  <head>
    <ThemeScript />
  </head>
  <body>…</body>
</html>

Give ThemeScript the same storageKey and defaultValue as the toggles if you change them. In a single-page app without server rendering, put the script's contents in index.html instead, or accept one frame in the default theme.

#Reference