useTheme

The useTheme composable provides comprehensive theme management capabilities, allowing you to register multiple themes, switch between them dynamically, and automatically generate CSS custom properties. Built on createSingle for single-theme selection and createTokens for design token alias resolution.

Copy Page as Markdown

Intermediate96.7% coverageJan 11, 2026

Installation

Install the Theme plugin in your app’s entry point:

main.ts

import { createApp } from 'vue'
import { createThemePlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(
  createThemePlugin({
    default: 'light',
    themes: {
      light: {
        dark: false,
        colors: {
          primary: '#3b82f6',
        },
      },
      dark: {
        dark: true,
        colors: {
          primary: '#675496',
        },
      },
    },
  })
)

app.mount('#app')

Usage

Once the plugin is installed, use the useTheme composable in any component:

UseTheme

<script setup lang="ts">
  import { useTheme } from '@vuetify/v0'

  const theme = useTheme()

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

<template>
  <div>
    <h1>Current Theme: {{ theme.selectedId }}</h1>
    <p>Dark mode: {{ theme.isDark ? 'enabled' : 'disabled' }}</p>
    <button @click="toggleTheme">Toggle Theme</button>
  </div>
</template>

Architecture

useTheme extends createSingle for theme selection and createTokens for color resolution:

API Reference

The following API details are for the useTheme composable.

Functions

createTheme

(_options?: ThemeOptions<ThemeRecord>) => R

Creates a new theme instance.

createThemeContext

(_options?: ThemeContextOptions) => ContextTrinity<R>

Creates a new theme context trinity.

createThemePlugin

(_options?: ThemePluginOptions) => any

Creates a new theme plugin.

useTheme

(namespace?: string) => R

Returns the current theme instance.

Options

events

boolean

Enable event emission for registry operations

Default: false

reactive

boolean

Enable reactive behavior for registry operations

Default: false

adapter

ThemeAdapter

The theme adapter to use.

default

ID

The default theme ID to select on initialization.

palette

TokenCollection

A collection of tokens to use for resolving theme colors.

themes

Record<ID, Z>

A record of themes to register.

target

string | HTMLElement

The target element or selector to apply theme classes to.

Properties

collection

ReadonlyMap<ID, Z>

The collection of tickets in the registry

size

number

The number of tickets in the registry

selectedIds

Reactive<Set<ID>>

Set of selected ticket IDs

selectedItems

ComputedRef<Set<E>>

Set of selected ticket instances

selectedValues

ComputedRef<Set<unknown>>

Set of selected ticket values

disabled

MaybeRef<boolean>

Disable state for the entire selection instance

selectedId

ComputedRef<any>

selectedIndex

ComputedRef<number>

selectedItem

ComputedRef<E>

selectedValue

ComputedRef<E["value"]>

colors

ComputedRef<Record<string, Colors>>

A computed reference to the resolved colors of the current theme.

isDark

Readonly<Ref<boolean, boolean>>

A ref indicating whether the current theme is dark.

Methods

clear

() => void

Clear the entire registry

has

(id: ID) => boolean

Check if a ticket exists by ID

keys

() => ID[]

Get all registered IDs

browse

(value: unknown) => ID[] | undefined

Browse for an ID(s) by value

lookup

(index: number) => ID | undefined

lookup a ticket by index number

get

(id: ID) => Z | undefined

Get a ticket by ID

upsert

(id: ID, ticket?: Partial<Z>) => Z

Update or insert a ticket by ID

values

() => Z[]

Get all values of registered tickets

entries

() => [ID, Z][]

Get all entries of registered tickets

unregister

(id: ID) => void

Unregister an ticket by ID

reindex

() => void

Reset the index directory and update all tickets

seek

(direction?: "first" | "last", from?: number, predicate?: (ticket) => boolean) => Z | undefined

Seek for a ticket based on direction and optional predicate

on

(event: string, cb: RegistryEventCallback) => void

Listen for registry events

off

(event: string, cb: RegistryEventCallback) => void

Stop listening for registry events

emit

(event: string, data: unknown) => void

Emit an event with data

dispose

() => void

Clears the registry and removes all listeners

offboard

(ids: ID[]) => void

Offboard multiple tickets at once

batch

<R>(fn: () => R) => R

Execute operations in a batch, deferring cache invalidation and event emission until complete

reset

() => void

Clear all selected IDs and reindexes

select

(id: ID) => void

Select a ticket by ID (Toggle ON)

unselect

(id: ID) => void

Unselect a ticket by ID (Toggle OFF)

toggle

(id: ID) => void

Toggles a ticket ON and OFF by ID

selected

(id: ID) => boolean

Check if a ticket is selected by ID

mandate

() => void

Mandates selected ID based on "mandatory" Option

onboard

(registrations: Partial<Z>[]) => E[]

Onboard multiple tickets at once

cycle

(themes?: ID[]) => void

Cycles through the provided themes in order.

register

(registration?: Partial<Z>) => E