1---
2category: Browser
3related:
4  - useDark
5  - usePreferredDark
6  - useStorage
7---
8 
9# useColorMode
10 
11Reactive color mode (dark / light / customs) with auto data persistence.
12 
13## Basic Usage
14 
15```ts
16import { useColorMode } from '@vueuse/core'
17 
18const mode = useColorMode() // Ref<'dark' | 'light'>
19```
20 
21By default, it will match with users' browser preference using `usePreferredDark` (a.k.a `auto` mode). When reading the ref, it will by default return the current color mode (`dark`, `light` or your custom modes). The `auto` mode can be included in the returned modes by enabling the `emitAuto` option. When writing to the ref, it will trigger DOM updates and persist the color mode to local storage (or your custom storage). You can pass `auto` to set back to auto mode.
22 
23```ts
24import { useColorMode } from '@vueuse/core'
25 
26const mode = useColorMode()
27// ---cut---
28mode.value // 'dark' | 'light'
29 
30mode.value = 'dark' // change to dark mode and persist
31 
32mode.value = 'auto' // change to auto mode
33```
34 
35## Config
36 
37```ts
38import { useColorMode } from '@vueuse/core'
39 
40const mode = useColorMode({
41  attribute: 'theme',
42  modes: {
43    // custom colors
44    dim: 'dim',
45    cafe: 'cafe',
46  },
47}) // Ref<'dark' | 'light' | 'dim' | 'cafe'>
48```
49 
50## Advanced Usage
51 
52You can also explicit access to the system preference and storaged user override mode.
53 
54```ts
55import { useColorMode } from '@vueuse/core'
56 
57const { system, store } = useColorMode()
58 
59system.value // 'dark' | 'light'
60store.value // 'dark' | 'light' | 'auto'
61 
62const myColorMode = computed(() => store.value === 'auto' ? system.value : store.value)
63```
64 
65## Component Usage
66 
67```vue
68<template>
69  <UseColorMode v-slot="color">
70    <button @click="color.mode = color.mode === 'dark' ? 'light' : 'dark'">
71      Mode {{ color.mode }}
72    </button>
73  </UseColorMode>
74</template>
75```
76 
77## Type Declarations
78 
79```ts
80export type BasicColorMode = "light" | "dark"
81export type BasicColorSchema = BasicColorMode | "auto"
82export interface UseColorModeOptions<
83  T extends string = BasicColorMode,
84> extends UseStorageOptions<T | BasicColorMode> {
85  /**
86   * CSS Selector for the target element applying to
87   *
88   * @default 'html'
89   */
90  selector?: string | MaybeElementRef
91  /**
92   * HTML attribute applying the target element
93   *
94   * @default 'class'
95   */
96  attribute?: string
97  /**
98   * The initial color mode
99   *
100   * @default 'auto'
101   */
102  initialValue?: MaybeRefOrGetter<T | BasicColorSchema>
103  /**
104   * Prefix when adding value to the attribute
105   */
106  modes?: Partial<Record<T | BasicColorSchema, string>>
107  /**
108   * A custom handler for handle the updates.
109   * When specified, the default behavior will be overridden.
110   *
111   * @default undefined
112   */
113  onChanged?: (
114    mode: T | BasicColorMode,
115    defaultHandler: (mode: T | BasicColorMode) => void,
116  ) => void
117  /**
118   * Custom storage ref
119   *
120   * When provided, `useStorage` will be skipped
121   */
122  storageRef?: Ref<T | BasicColorSchema>
123  /**
124   * Key to persist the data into localStorage/sessionStorage.
125   *
126   * Pass `null` to disable persistence
127   *
128   * @default 'vueuse-color-scheme'
129   */
130  storageKey?: string | null
131  /**
132   * Storage object, can be localStorage or sessionStorage
133   *
134   * @default localStorage
135   */
136  storage?: StorageLike
137  /**
138   * Emit `auto` mode from state
139   *
140   * When set to `true`, preferred mode won't be translated into `light` or `dark`.
141   * This is useful when the fact that `auto` mode was selected needs to be known.
142   *
143   * @default undefined
144   * @deprecated use `store.value` when `auto` mode needs to be known
145   * @see https://vueuse.org/core/useColorMode/#advanced-usage
146   */
147  emitAuto?: boolean
148  /**
149   * Disable transition on switch
150   *
151   * @see https://paco.me/writing/disable-theme-transitions
152   * @default true
153   */
154  disableTransition?: boolean
155}
156export type UseColorModeReturn<T extends string = BasicColorMode> = Ref<
157  T | BasicColorSchema
158> & {
159  store: Ref<T | BasicColorSchema>
160  system: ComputedRef<BasicColorMode>
161  state: ComputedRef<T | BasicColorMode>
162}
163/**
164 * Reactive color mode with auto data persistence.
165 *
166 * @see https://vueuse.org/useColorMode
167 * @param options
168 */
169export declare function useColorMode<T extends string = BasicColorMode>(
170  options?: UseColorModeOptions<T>,
171): UseColorModeReturn<T>
172```
173