Skip to main content

​
Overview

The useTheme() composable provides access to Vuetify’s theme system, allowing you to read current theme values, switch between themes, and manage theme state reactively.

​
Import

import { useTheme } from 'vuetify'

​
Signature

function useTheme(): ThemeInstance

​
Return Value

Returns a ThemeInstance object with the following properties and methods:
​
name
Readonly<Ref<string>>
The name of the currently active theme (e.g., ‘light’, ‘dark’, or custom theme name)
​
current
DeepReadonly<Ref<InternalThemeDefinition>>
The complete current theme definition including colors and variables
​
themes
Ref<Record<string, InternalThemeDefinition>>
All available theme definitions
​
computedThemes
DeepReadonly<Ref<Record<string, InternalThemeDefinition>>>
Computed themes with variations and generated on-colors
​
isDisabled
boolean
Whether the theme system is disabled
​
isSystem
Readonly<Ref<boolean>>
Whether the theme is set to follow system preferences
​
prefix
string
CSS variable prefix (default: ‘v-’)
​
themeClasses
Readonly<Ref<string | undefined>>
CSS classes to apply based on current theme
​
styles
Readonly<Ref<string>>
Generated CSS styles for the theme
​
global
object
Global theme reference with name and current properties

​
Methods

​
change
(themeName: string) => void
Switch to a different theme by nameParameters:
  • themeName - Name of the theme to activate (e.g., ‘light’, ‘dark’, ‘system’)
​
cycle
(themeArray?: string[]) => void
Cycle through an array of themesParameters:
  • themeArray - Optional array of theme names to cycle through (defaults to all themes)
​
toggle
(themeArray?: [string, string]) => void
Toggle between two themesParameters:
  • themeArray - Optional tuple of two theme names (defaults to [‘light’, ‘dark’])

​
Theme Definition

interface ThemeDefinition {
  dark: boolean
  colors: {
    background: string
    surface: string
    primary: string
    secondary: string
    success: string
    warning: string
    error: string
    info: string
    'on-background': string
    'on-surface': string
    'on-primary': string
    // ... and more
    [key: string]: string
  }
  variables: Record<string, string | number>
}

​
Usage Examples

​
Basic Usage

<script setup>
import { useTheme } from 'vuetify'

const theme = useTheme()

// Get current theme name
console.log(theme.name.value) // 'light' or 'dark'

// Get current theme colors
console.log(theme.current.value.colors.primary) // '#1867C0'
</script>

​
Switch Themes

<script setup>
import { useTheme } from 'vuetify'

const theme = useTheme()

function switchToDark() {
  theme.change('dark')
}

function switchToLight() {
  theme.change('light')
}

function toggleTheme() {
  theme.toggle() // Toggles between light and dark
}
</script>

<template>
  <v-btn @click="toggleTheme">
    Toggle {{ theme.name }}
  </v-btn>
</template>

​
Access Theme Colors

<script setup>
import { useTheme } from 'vuetify'
import { computed } from 'vue'

const theme = useTheme()

const primaryColor = computed(() => theme.current.value.colors.primary)
const backgroundColor = computed(() => theme.current.value.colors.background)
</script>

<template>
  <div :style="{ backgroundColor }">
    <h1 :style="{ color: primaryColor }">
      Themed Content
    </h1>
  </div>
</template>

​
Cycle Through Custom Themes

<script setup>
import { useTheme } from 'vuetify'

const theme = useTheme()

function cycleThemes() {
  theme.cycle(['light', 'dark', 'custom'])
}
</script>

​
Check System Theme Preference

<script setup>
import { useTheme } from 'vuetify'
import { watch } from 'vue'

const theme = useTheme()

watch(() => theme.isSystem.value, (isSystem) => {
  if (isSystem) {
    console.log('Following system theme preference')
  }
})
</script>

​
Notes

  • Must be called within a component setup function or composable
  • Throws an error if the Vuetify theme provider is not found
  • Theme changes are reactive and will update all dependent components
  • The system theme name will automatically follow OS preferences

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us