Theme

Set up the theme in the root layout so every page reads the same preference before rendering. ThemeToggle only changes that shared state; it does not replace ThemeProvider or ThemeScript.

When to use

Apps that need to remember the preferred light or dark theme
A header action that switches the current theme

Wrap the page content with ThemeProvider in the root layout to manage theme state. Place ThemeScript in head to apply the theme before the content appears. Add ThemeToggle to switch themes, usually in the header.

Usage

src/app/layout.tsx

TSX

import { ThemeProvider } from 'blackwork'
import { ThemeScript } from 'blackwork/rsc'

const RootLayout = ({ children }: React.PropsWithChildren) => {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}

export default RootLayout

Usage

Examples

Dropdown

API Reference

Prop	Type	Default	Description
`defaultTheme`	`"light" \| "dark"`	`"dark"`	Initial theme on ThemeProvider.
`storageKey`	`string`	`"blackwork-theme"`	localStorage key on ThemeProvider.
`mode`	`"button" \| "dropdown"`	`"button"`	Interaction on ThemeToggle.
`options`	`ThemeToggleOption[]`	—	Custom labels and icons for ThemeToggle.
`ariaLabel`	`string`	—	Accessible name for ThemeToggle.

Notes

Default theme is dark.
The preference is stored in localStorage under blackwork-theme.
Keep storageKey and defaultTheme identical on ThemeScript and ThemeProvider.
This site configures ThemeProvider in the root layout, so the previews above use the site’s theme state.
If the application follows the system theme, include system in the toggle values and keep the default explicit.