@codefast/theme

Theme management with React 19 features - optimistic updates, cross-tab sync, and SSR support.

Features

- 🚀 React 19 Optimized - Uses useOptimistic, useSyncExternalStore, useEffectEvent
- 🌗 System Theme Detection - Automatically detects and follows OS preference
- 🔄 Cross-tab Sync - Theme changes sync across all open tabs
- ⚡ Optimistic Updates - Immediate UI feedback during theme changes
- 🎯 SSR Ready - FOUC prevention with inline script
- 🔌 Framework Adapters - Built-in TanStack Start adapter, extensible for others

Installation

``bash
pnpm add @codefast/theme
`

Usage

$3

`tsx
// routes/__root.tsx
import { ThemeProvider, ThemeScript, resolveTheme } from '@codefast/theme';
import { getThemeServerFn, setThemeServerFn } from '@codefast/theme/tanstack-start';

export const Route = createRootRoute({
loader: async () => {
const theme = await getThemeServerFn();
return { theme };
},
component: RootComponent,
head: ({ loaderData }) => ({
scripts: [
{ tag: ThemeScript, props: { theme: loaderData?.theme ?? 'system' } },
],
}),
});

function RootComponent() {
const { theme } = Route.useLoaderData();

return (
theme={theme}
persistTheme={(value) => setThemeServerFn({ data: value })}
>


);
}
`

$3

`tsx
import { useTheme, themes } from '@codefast/theme';

function ThemeToggle() {
const { theme, setTheme, isPending } = useTheme();

return (
value={theme}
onChange={(e) => setTheme(e.target.value)}
disabled={isPending}
>
{themes.map((t) => (
{t}
))}

);
}
`

API

$3

| Prop | Type | Description |
|------|------|-------------|
| theme | Theme | Initial theme value |
| persistTheme | (value: Theme) => Promise | Callback to persist theme |
| disableTransitionOnChange | boolean | Disable CSS transitions during theme change |
| nonce | string | CSP nonce for inline styles |

$3

Returns ThemeContextType:

| Property | Type | Description |
|----------|------|-------------|
| theme | Theme | Current theme preference |
| resolvedTheme | ResolvedTheme | Resolved theme ('light' or 'dark') |
| setTheme | (value: Theme) => Promise | Set theme function |
| isPending | boolean` | Whether theme change is in progress |

License

MIT