feat(theme): add change, toggle, and cycle functions (#21224)

Author: johnleider

packages/api-generator/src/locale/en/useTheme.json

@@ -1,5 +1,8 @@
 {
   "exposed": {
+    "change": "Change to a specific theme.",
+    "toggle": "Toggle between two themes.",
+    "cycle": "Cycle between all or a subset of themes.",
     "computedThemes": "Object containing all parsed theme definitions.",
     "current": "Current theme object.",
     "global": "Reference to the global theme instance.",

packages/docs/src/data/new-in.json

@@ -1,4 +1,11 @@
 {
+  "useTheme": {
+    "exposed": {
+      "change": "3.9.0",
+      "toggle": "3.9.0",
+      "cycle": "3.9.0"
+    }
+  },
   "VAppBar": {
     "props": {
       "scrollBehavior": "3.2.0"

packages/docs/src/data/page-to-api.json

@@ -173,7 +173,7 @@
   "features/scrolling": ["useGoTo"],
   "features/global-configuration": ["VDefaultsProvider"],
   "features/internationalization": ["useLocale", "VLocaleProvider"],
-  "features/theme": ["VThemeProvider"],
+  "features/theme": ["useTheme", "VThemeProvider"],
   "styles/transitions": [
     "VDialogBottomTransition",
     "VDialogTopTransition",

packages/docs/src/pages/en/features/theme.md

@@ -153,7 +153,56 @@ export default createVuetify({
 
 ## Changing theme
 
-This is used when you need to change the theme during runtime
+The theme instance has 3 functions to change the theme:
+
+- **change**: Change to a specific name
+- **toggle**: Toggle between two themes / defaults to light and dark
+- **cycle**: Cycle between all or a specific subset of themes in any order
+
+```html
+<template>
+  <v-app>
+    <v-main>
+      <v-container>
+        <!-- Toggle between Light / Dark -->
+        <v-btn
+          @click="theme.toggle()"
+          text="Toggle Light / Dark"
+        ></v-btn>
+
+        <!-- Change to a specific theme -->
+        <v-btn
+          @click="theme.change('dark')"
+          text="Change to Dark"
+        ></v-btn>
+
+        <!-- Cycle between all themes -->
+        <v-btn
+          @click="theme.cycle()"
+          text="Cycle All Themes"
+        ></v-btn>
+
+        <!-- Cycle between specific themes -->
+        <v-btn
+          @click="theme.cycle(['custom', 'light', 'utopia'])"
+          text="Cycle Specific Themes"
+        ></v-btn>
+      </v-container>
+    </v-main>
+  </v-app>
+</template>
+
+<script setup>
+  import { useTheme } from 'vuetify'
+
+  const theme = useTheme()
+</script>
+```
+
+<details>
+<summary>Usage before v3.9</summary>
+
+In versions before v3.9, you manually change the global name value on the theme instance:
 
 ```html { resource="src/App.vue" }
 <template>
@@ -174,6 +223,10 @@ function toggleTheme () {
 </script>
 ```
 
+</details>
+
+<br>
+
 You should keep in mind that most of the Vuetify components support the **theme** prop. When used a new context is created for _that_ specific component and **all** of its children. In the following example, the [v-btn](/components/buttons/) uses the **dark** theme because it is applied to its parent [v-card](/components/cards/).
 
 ```html

packages/vuetify/src/composables/__tests__/theme.spec.ts

@@ -228,4 +228,50 @@ describe('createTheme', () => {
     // Verify updateDOM is called during reactivity
     expect(mockUpdateHead).toHaveBeenCalled()
   })
+
+  it('should change, toggle, and cycle theme', async () => {
+    const theme = createTheme({
+      defaultTheme: 'light',
+      themes: {
+        custom: { dark: false },
+        utopia: { dark: true },
+      },
+    })
+
+    // Test 1: Toggle through all available themes when no argument provided
+    expect(theme.name.value).toBe('light')
+
+    theme.toggle()
+    expect(theme.name.value).toBe('dark')
+
+    theme.toggle()
+    expect(theme.name.value).toBe('light')
+
+    // Test 2: Change to a specific theme
+    theme.change('dark')
+    expect(theme.name.value).toBe('dark')
+
+    // Test 3: Cycle between a limited set of themes
+    theme.cycle()
+    expect(theme.name.value).toBe('custom')
+
+    theme.cycle()
+    expect(theme.name.value).toBe('utopia')
+
+    theme.cycle()
+    expect(theme.name.value).toBe('light')
+
+    // Test 4: Cycle between a subset of themes
+    theme.cycle(['light', 'utopia'])
+    expect(theme.name.value).toBe('utopia')
+
+    theme.cycle(['light', 'utopia'])
+    expect(theme.name.value).toBe('light')
+
+    // Test 5: Error when changing to a non-existent theme
+    const consoleMock = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    theme.change('nonexistent')
+    expect(consoleMock).toHaveBeenCalledWith('[Vue warn]: Vuetify: Theme "nonexistent" not found on the Vuetify theme instance')
+    consoleMock.mockReset()
+  })
 })

packages/vuetify/src/composables/theme.ts

@@ -9,8 +9,10 @@ import {
   watchEffect,
 } from 'vue'
 import {
+  consoleWarn,
   createRange,
   darken,
+  deprecate,
   getCurrentInstance,
   getForeground,
   getLuma,
@@ -88,6 +90,10 @@ interface OnColors {
 }
 
 export interface ThemeInstance {
+  change: (themeName: string) => void
+  cycle: (themeArray?: string[]) => void
+  toggle: (themeArray?: [string, string]) => void
+
   readonly isDisabled: boolean
   readonly themes: Ref<Record<string, InternalThemeDefinition>>
 
@@ -386,6 +392,9 @@ export function createTheme (options?: ThemeOptions): ThemeInstance & { install:
     return lines.map((str, i) => i === 0 ? str : `    ${str}`).join('')
   })
 
+  const themeClasses = computed(() => parsedOptions.isDisabled ? undefined : `v-theme--${name.value}`)
+  const themeNames = computed(() => Object.keys(computedThemes.value))
+
   function install (app: App) {
     if (parsedOptions.isDisabled) return
 
@@ -430,10 +439,45 @@ export function createTheme (options?: ThemeOptions): ThemeInstance & { install:
     }
   }
 
-  const themeClasses = computed(() => parsedOptions.isDisabled ? undefined : `v-theme--${name.value}`)
+  function change (themeName: string) {
+    if (!themeNames.value.includes(themeName)) {
+      consoleWarn(`Theme "${themeName}" not found on the Vuetify theme instance`)
+      return
+    }
+
+    name.value = themeName
+  }
+
+  function cycle (themeArray: string[] = themeNames.value) {
+    const currentIndex = themeArray.indexOf(name.value)
+    const nextIndex = currentIndex === -1 ? 0 : (currentIndex + 1) % themeArray.length
+
+    change(themeArray[nextIndex])
+  }
+
+  function toggle (themeArray: [string, string] = ['light', 'dark']) {
+    cycle(themeArray)
+  }
+
+  const globalName = new Proxy(name, {
+    get (target, prop) {
+      return target[prop as keyof typeof target]
+    },
+    set (target, prop, val) {
+      if (prop === 'value') {
+        deprecate(`theme.global.name.value = ${val}`, `theme.change('${val}')`)
+      }
+      // @ts-expect-error
+      target[prop] = val
+      return true
+    },
+  }) as typeof name
 
   return {
     install,
+    change,
+    cycle,
+    toggle,
     isDisabled: parsedOptions.isDisabled,
     name,
     themes,
@@ -442,7 +486,7 @@ export function createTheme (options?: ThemeOptions): ThemeInstance & { install:
     themeClasses,
     styles,
     global: {
-      name,
+      name: globalName,
       current,
     },
   }