https://github.com/aakashns/tanstack-router-theme-provider
SSR-friendly dark mode provider & useTheme hook for TanStack Router & TanStack Start
https://github.com/aakashns/tanstack-router-theme-provider
javascript react tanstack-router tanstack-start
Last synced: about 1 month ago
JSON representation
SSR-friendly dark mode provider & useTheme hook for TanStack Router & TanStack Start
- Host: GitHub
- URL: https://github.com/aakashns/tanstack-router-theme-provider
- Owner: aakashns
- Created: 2026-04-12T08:15:43.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T09:52:23.000Z (3 months ago)
- Last Synced: 2026-04-12T10:22:30.436Z (3 months ago)
- Topics: javascript, react, tanstack-router, tanstack-start
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/tanstack-router-theme-provider
- Size: 92.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# tanstack-router-theme-provider [](https://www.npmjs.com/package/tanstack-router-theme-provider)
SSR-friendly `` and `useTheme` hook for dark mode support in TanStack Router and TanStack Start apps.
## Features
- Perfect dark mode support in 2 lines of code
- Supports `light`, `dark`, and `system` themes
- Compatible with [shadcn-ui](https://ui.shadcn.com) out-of-the-box
- Persists the selected theme in `localStorage`
- Applies `dark` or `light` class to the root ``
- Sets the browser `color-scheme` automatically
- Syncs theme changes across browser tabs instantaneously
- Includes startup script to prevent avoid theme flicker on first paint (FOUC)
## Installation
```bash
npm install tanstack-router-theme-provider
```
Peer dependencies:
- `react` `>=18.0.0`
- `react-dom` `>=18.0.0`
- `@tanstack/react-router` `>=1.0.0`
## Usage
Wrap your root route (`src/routes/__root.tsx`) with `` and add `supressHydrationWarning` on the `` tag:
```tsx
// add this after existing imports..
import { ThemeProvider } from 'tanstack-router-theme-provider'
function RootComponent() {
return (
)
}
export const Route = createRootRoute({
components: RootComponent,
// other code..
})
```
Use `useTheme` anywhere below the provider.
```tsx
import { useTheme } from 'tanstack-router-theme-provider'
export function ThemeToggle() {
const { theme, resolvedTheme, setTheme, mounted } = useTheme()
if (!mounted) return null
return (
setTheme(theme === 'dark' ? 'light' : 'dark')}>
Current theme: {theme} ({resolvedTheme})
)
}
```
How it works:
- `theme` can have the value `light`, `dark`, or `system` (i.e. OS setting)
- `setTheme` stores the provided theme in `localStorage` on the client
- `resolvedTheme` is `undefined` on the server (i.e. during SSR) since `localStorage` is not accessible there
- `resolvedTheme` is `light` or `dark` on the client based on the `prefers-color-scheme: dark` media query
- `mounted` is `false` on the server (i.e. during SSR) and `true` on the client
## Reference
You can customize the `ThemeProvider` provider using the following props:
| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | The app content rendered inside the provider. | Required |
| `defaultTheme` | `'dark' \| 'light' \| 'system'` | The initial theme to use when there is no saved value in storage. | `'system'` |
| `storageKey` | `string` | The `localStorage` key used to persist the selected theme. | `'tanstack-ui-theme'` |
## Development
- Install dependencies:
```bash
npm install
```
- Build the library:
```bash
npm run build
```