vartheme
v0.1.6 — Documentation

Documentation

Everything you need to use vartheme in your project.

On this page
InstallationBasic SetupNext.js App RouteruseThemeContext HookBuilt-in Themesshadcn/ui + Radix SupportCustom ColorsCSS VariablesTailwind PluginonThemeChange Callback

Installation

Install vartheme from npm. No peer dependencies required.

BASH
1
npm install vartheme

Basic Setup

Wrap your app with ThemeProvider. That's it.

TSX
1
import { ThemeProvider, ThemeToggle } from 'vartheme'
2


3
export default function App() {
4
  return (
5
    <ThemeProvider mode="system" transitions>
6
      <ThemeToggle />
7
      <YourApp />
8
    </ThemeProvider>
9
  )
10
}

Next.js App Router

getFOUCScript() prevents white flash before React hydrates. Always add it in <head>.

TSX
1
// app/layout.tsx
2
import { getFOUCScript } from 'vartheme'
3
import { ThemeProvider } from 'vartheme'
4


5
export default function RootLayout({ children }) {
6
  return (
7
    <html suppressHydrationWarning>
8
      <head>
9
        <script dangerouslySetInnerHTML={{ __html: getFOUCScript() }} />
10
      </head>
11
      <body>
12
        <ThemeProvider>{children}</ThemeProvider>
13
      </body>
14
    </html>
15
  )
16
}

useThemeContext Hook

Access and control the theme from any component inside ThemeProvider.

TSX
1
import { useThemeContext } from 'vartheme'
2


3
function MyComponent() {
4
  const {
5
    mode,           // 'light' | 'dark' | 'system'
6
    resolvedMode,   // 'light' | 'dark' (actual)
7
    theme,          // 'default' | 'ocean' | ...
8
    colors,         // current color object
9
    toggle,         // toggle light/dark
10
    setMode,        // set specific mode
11
    setTheme,       // set named theme
12
    setColors,      // set custom colors
13
  } = useThemeContext()
14


15
  return <button onClick={toggle}>{resolvedMode}</button>
16
}

Built-in Themes

5 beautiful built-in themes. Switch at any time.

TSX
1
// 5 built-in themes
2
<ThemeProvider theme="default">  // purple
3
<ThemeProvider theme="ocean">    // blue
4
<ThemeProvider theme="forest">   // green
5
<ThemeProvider theme="sunset">   // orange
6
<ThemeProvider theme="rose">     // pink
7


8
// Switch at runtime
9
const { setTheme } = useThemeContext()
10
setTheme('ocean')

shadcn/ui + Radix Support

Full compatibility with shadcn/ui, Radix UI, DaisyUI and any design system.

TSX
1
// class="dark" — for shadcn/ui
2
<ThemeProvider strategy={{ type: 'class' }}>
3


4
// data-theme="dark" + class="dark" — both
5
<ThemeProvider strategy={{ type: 'both' }}>
6


7
// Custom attribute
8
<ThemeProvider strategy={{ type: 'data-attribute', attribute: 'data-mode' }}>

Custom Colors

Override any color statically or dynamically at runtime.

TSX
1
// Static
2
<ThemeProvider colors={{ primary: '#EC4899', accent: '#F59E0B' }}>
3


4
// Dynamic at runtime
5
const { setColors } = useThemeContext()
6
setColors({ primary: '#10B981' })

CSS Variables

vartheme auto-injects CSS variables on <html>. Use them anywhere.

CSS
1
.card {
2
  background: var(--vt-surface);
3
  color: var(--vt-text);
4
  border: 1px solid var(--vt-border);
5
}
6


7
.btn {
8
  background: var(--vt-primary);
9
  color: white;
10
}

Tailwind Plugin

Use vartheme CSS variables directly as Tailwind utility classes.

TSX
1
// tailwind.config.js
2
import { varthemePlugin } from 'vartheme/tailwind'
3


4
export default {
5
  plugins: [varthemePlugin],
6
}
7


8
// Usage in JSX
9
<div className="bg-vt-surface text-vt-text border border-vt-border">
10
  <h1 className="text-vt-primary">Hello!</h1>
11
</div>

onThemeChange Callback

Get notified whenever the theme changes. Perfect for analytics.

TSX
1
<ThemeProvider
2
  onThemeChange={(mode) => {
3
    // Analytics, logging, side effects
4
    analytics.track('theme_switch', { mode })
5
    console.log('Theme changed to:', mode)
6
  }}
7
>