Guia · Fundamentos
Configuração de tema
Light e dark são definidos por tokens CSS. Basta mudar o atributo data-theme; nenhum componente precisa ser re-renderizado.
O atributo data-theme
Os tokens --v-* têm valores padrão em :root e são redefinidos em [data-theme="dark"]. Com system, a lib usa a media query prefers-color-scheme.
<!-- o tema vem do atributo data-theme em um ancestral (normalmente <html>) -->
<html data-theme="light"> <!-- claro -->
<html data-theme="dark"> <!-- escuro -->
<html data-theme="system"> <!-- segue prefers-color-scheme -->Troca em runtime com useTheme()
O composable useTheme() aplica o atributo, persiste a escolha em localStorage e expõe o tema resolvido (light ou dark).
<script setup lang="ts">
import { useTheme, VButton } from 'vueui-nova-kit'
const { theme, resolvedTheme, setTheme, toggleTheme } = useTheme({
default: 'system', // 'light' | 'dark' | 'system'
storageKey: 'v-theme', // false desativa a persistência
// target: document.documentElement (padrão)
})
</script>
<template>
<VButton variant="secondary" @click="toggleTheme()">
Tema: {{ resolvedTheme }}
</VButton>
<VButton variant="ghost" @click="setTheme('system')">Seguir o sistema</VButton>
</template>Veja a referência completa de useTheme.
Tema por seção
Como o tema é um atributo, ele vale para toda a subárvore e pode ser aplicado só em uma seção.
<!-- data-theme vale para a subárvore: dá para ter uma seção escura numa página clara -->
<section data-theme="dark">
<VCard>Sempre escuro</VCard>
</section>Evitando flash (SSR)
Em apps renderizados no servidor, aplique o tema salvo com um script inline no <head>, antes da primeira pintura. Este site usa exatamente este script.
// nuxt.config.ts — aplica o tema salvo antes da primeira pintura
const themeScript = `(function(){try{
var s = localStorage.getItem('v-theme');
var t = (s === 'light' || s === 'dark') ? s
: (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
document.documentElement.setAttribute('data-theme', t);
}catch(e){}})();`
export default defineNuxtConfig({
app: { head: { script: [{ innerHTML: themeScript, tagPosition: 'head' }] } },
})O toggle deste site
O botão de sol/lua no cabeçalho chama useTheme().setTheme() e grava a escolha na chave v-theme. Na primeira visita, o site segue a preferência do sistema operacional.
/* seus estilos também podem reagir ao tema usando os tokens */
.minha-caixa {
background: var(--v-color-surface);
color: var(--v-color-text);
border: 1px solid var(--v-color-border);
}
[data-theme='dark'] .minha-caixa {
box-shadow: none;
}