useTheme

Theme
stable

Module-level singleton managing the brand theme axis (data-theme attribute) and the color-mode axis (data-mode attribute). Persists both axes to localStorage and reacts to prefers-color-scheme. Every call to useTheme() shares the same refs.

API

Signature

Full TypeScript signature sourced from the composable file.

typescript

useTheme() is a module-level singleton — all components share the same refs. The prefers-color-scheme listener is initialised once (not in onMounted), so resolvedMode is correct even when called from a Nuxt plugin before the first component renders.

API

Return values

Properties and methods exposed by the composable return object.

theme
The current brand theme value: 'auto' | 'light' | 'dark' | string (custom brand). Read-only reactive ref.
resolved
Effective theme after resolving 'auto' against prefers-color-scheme. Always 'light' or 'dark'.
setTheme
Sets the brand theme, applies data-theme to <html> and persists to localStorage.
toggle
Convenience: flips the brand light ↔ dark. Treats 'auto' as light.
mode
The current color mode: 'auto' | 'light' | 'dark'. Read-only reactive ref.
resolvedMode
Effective mode after resolving 'auto' against prefers-color-scheme. Always 'light' or 'dark'.
setMode
Sets the color mode, applies data-mode to <html> and persists to localStorage.
toggleMode
Flips the color mode light ↔ dark. Treats 'auto' as the current system preference.

Usage

Examples

Ready-to-paste usage snippets.

Dark mode toggle button

vue

Switch to a custom brand theme

vue