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.

index.html
<!-- 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).

Tema deste site agora: light
Primária
ThemeSwitch.vue
<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.

html
<!-- 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
// 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.

app.css
/* 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;
}