Theme

When to use

Any app that should remember light or dark
A header action that switches the current theme

Wrap the tree once with ThemeProvider and put ThemeScript in head to prevent the wrong theme from flashing during page load. Put ThemeToggle where users expect theme controls.

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 docs site already mounts ThemeProvider in the root layout.