useTheme
Read and change the color mode (light, dark, or automatic) applied to EletroDS components.
Overview
useTheme() wraps the color-mode mechanism that @nuxt/ui already sets up (light/dark class on <html>, persisted to localStorage), and additionally sets a data-theme="light" / data-theme="dark" attribute on <html> for any custom CSS in your application that wants to key off it directly. When the mode is auto, data-theme is removed and the browser's own prefers-color-scheme decides.
It is the composable behind the built-in "Modo" selector in MeHeader's avatar dropdown, and is also exported for standalone use anywhere in your app.
Usage
import { useTheme } from '@mercadoeletronico/eds-next'
const { mode, setMode, isDark } = useTheme()
// mode.value: 'light' | 'dark' | 'auto' (the user's raw preference, default 'auto')
// isDark.value: boolean (the resolved theme, useful for swapping icons)
setMode('dark')
API
| Name | Type | Description |
|---|---|---|
mode | Ref<'light' | 'dark' | 'auto'> | The user's raw preference. Defaults to 'auto'. |
setMode | (mode: 'light' | 'dark' | 'auto') => void | Updates the preference, persists it, and re-applies the theme immediately. |
isDark | ComputedRef<boolean> | The resolved theme (never 'auto') — true when the applied theme is dark, including when mode is 'auto' and the system prefers dark. |
Storage key
useTheme() persists the preference in localStorage under whichever key your app is already using, so it never creates a second, disconnected color-mode state:
- If your app is Nuxt-based (the
@nuxt/uiintegration registers the official@nuxtjs/color-modemodule), it uses that module's own default key,nuxt-color-mode. - If your app is a plain Vite app with no Nuxt runtime,
@nuxt/ui's Vite plugin falls back to VueUse'suseColorMode(), which persists undervueuse-color-scheme. - On a fresh install with neither key present yet, it defaults to
nuxt-color-mode(the official Nuxt convention).
Known limitation: SSR flash
useTheme() applies the theme on the client (on first call). Server-rendered applications (e.g. a Nuxt app) may briefly flash the wrong theme before hydration. If this matters for your app, add an inline script in your <head> that reads localStorage['nuxt-color-mode'] (or localStorage['vueuse-color-scheme'] for a plain-Vite host — see Storage key above) and sets the dark/light class before Vue mounts — this is an application-level concern, not something useTheme() handles for you.