useTheme

useTheme(): UseThemeReturn

Defined in: src/hooks/useTheme/useTheme.ts:169

Read the current theme at runtime.

Returns the resolved CSS variable snapshot from :root, the detected theme variant, and helpers for reading individual tokens by path. Components should prefer compile-time tokens via Vanilla Extract (vars.* from @/theme) — reach for useTheme only when a runtime read is genuinely required (canvas drawing, third-party libraries that take colors as plain strings).

Scope: the hook always reads from :root — both the variant and the resolved values come from document.documentElement. A light- or custom-themed subtree wrapped in VanillaThemeProvider will not be reflected here; for that, components inside the subtree should style via Vanilla Extract vars.* (which the browser resolves correctly per scope) rather than runtime reads.

SSR: returns the dark-theme defaults as a fallback. The hook re-evaluates against the live DOM on mount via useLayoutEffect, so the second render contains the real values before the browser paints.

Reactivity: v0.8 reads once on mount. Toggling the root theme at runtime is not reflected — remount the consuming subtree to pick up the new theme. A MutationObserver-based subscription may be added in a later release if consumer demand emerges.

Returns

UseThemeReturn

Example

const { values, variant, getVar, getToken } = useTheme();

// Canvas drawing with theme-aware colors
ctx.strokeStyle = values.colors.accent.primary;

// Conditional logic
if (variant === 'dark') loadDarkAssets();

// Inline styles that follow theme changes automatically
<div style={{ color: getVar('colors.text.primary') }} />

// One-off token resolution
const accent = getToken('colors.accent.primary');