useColorMode
Reactive color mode (dark / light / customs) with auto data persistence.
Demo
← Click to change the color mode
Basic Usage
import { useColorMode } from '@vueuse/core'
const mode = useColorMode() // Ref<'dark' | 'light'>
import { useColorMode } from '@vueuse/core'
const mode = useColorMode() // Ref<'dark' | 'light'>
By 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.
mode.value // 'dark' | 'light'
mode.value = 'dark' // change to dark mode and persist
mode.value = 'auto' // change to auto mode
mode.value // 'dark' | 'light'
mode.value = 'dark' // change to dark mode and persist
mode.value = 'auto' // change to auto mode
Config
import { useColorMode } from '@vueuse/core'
const mode = useColorMode({
attribute: 'theme',
modes: {
// custom colors
dim: 'dim',
cafe: 'cafe',
},
}) // Ref<'dark' | 'light' | 'dim' | 'cafe'>
import { useColorMode } from '@vueuse/core'
const mode = useColorMode({
attribute: 'theme',
modes: {
// custom colors
dim: 'dim',
cafe: 'cafe',
},
}) // Ref<'dark' | 'light' | 'dim' | 'cafe'>
Component Usage
This function also provides a renderless component version via the
@vueuse/componentspackage. Learn more about the usage.
<UseColorMode v-slot="{ mode }">
<button @click="mode = mode === 'dark' ? 'light' : 'dark'">
Mode {{ mode }}
</button>
</UseColorMode>
<UseColorMode v-slot="{ mode }">
<button @click="mode = mode === 'dark' ? 'light' : 'dark'">
Mode {{ mode }}
</button>
</UseColorMode>
Type Declarations
Show Type Declarations
export declare type BasicColorSchema = "light" | "dark" | "auto"
export interface UseColorModeOptions<T extends string = BasicColorSchema>
extends StorageOptions<T | BasicColorSchema> {
/**
* CSS Selector for the target element applying to
*
* @default 'html'
*/
selector?: string
/**
* HTML attribute applying the target element
*
* @default 'class'
*/
attribute?: string
/**
* Prefix when adding value to the attribute
*/
modes?: Partial<Record<T | BasicColorSchema, string>>
/**
* A custom handler for handle the updates.
* When specified, the default behavior will be overridded.
*
* @default undefined
*/
onChanged?: (
mode: T | BasicColorSchema,
defaultHandler: (mode: T | BasicColorSchema) => void
) => void
/**
* Custom storage ref
*
* When provided, `useStorage` will be skipped
*/
storageRef?: Ref<T | BasicColorSchema>
/**
* Key to persist the data into localStorage/sessionStorage.
*
* Pass `null` to disable persistence
*
* @default 'vueuse-color-scheme'
*/
storageKey?: string | null
/**
* Storage object, can be localStorage or sessionStorage
*
* @default localStorage
*/
storage?: StorageLike
/**
* Emit `auto` mode from state
*
* When set to `true`, preferred mode won't be translated into `light` or `dark`.
* This is useful when the fact that `auto` mode was selected needs to be known.
*
* @default undefined
*/
emitAuto?: boolean
}
/**
* Reactive color mode with auto data persistence.
*
* @see https://vueuse.org/useColorMode
* @param options
*/
export declare function useColorMode<T extends string = BasicColorSchema>(
options?: UseColorModeOptions<T>
): WritableComputedRef<BasicColorSchema | T>
export declare type BasicColorSchema = "light" | "dark" | "auto"
export interface UseColorModeOptions<T extends string = BasicColorSchema>
extends StorageOptions<T | BasicColorSchema> {
/**
* CSS Selector for the target element applying to
*
* @default 'html'
*/
selector?: string
/**
* HTML attribute applying the target element
*
* @default 'class'
*/
attribute?: string
/**
* Prefix when adding value to the attribute
*/
modes?: Partial<Record<T | BasicColorSchema, string>>
/**
* A custom handler for handle the updates.
* When specified, the default behavior will be overridded.
*
* @default undefined
*/
onChanged?: (
mode: T | BasicColorSchema,
defaultHandler: (mode: T | BasicColorSchema) => void
) => void
/**
* Custom storage ref
*
* When provided, `useStorage` will be skipped
*/
storageRef?: Ref<T | BasicColorSchema>
/**
* Key to persist the data into localStorage/sessionStorage.
*
* Pass `null` to disable persistence
*
* @default 'vueuse-color-scheme'
*/
storageKey?: string | null
/**
* Storage object, can be localStorage or sessionStorage
*
* @default localStorage
*/
storage?: StorageLike
/**
* Emit `auto` mode from state
*
* When set to `true`, preferred mode won't be translated into `light` or `dark`.
* This is useful when the fact that `auto` mode was selected needs to be known.
*
* @default undefined
*/
emitAuto?: boolean
}
/**
* Reactive color mode with auto data persistence.
*
* @see https://vueuse.org/useColorMode
* @param options
*/
export declare function useColorMode<T extends string = BasicColorSchema>(
options?: UseColorModeOptions<T>
): WritableComputedRef<BasicColorSchema | T>
Source
Contributors
Anthony Fu
Dominik Freier
wheat
Andreas Weber
Andrej Hýll