Skip to content

useColorMode

Category
Export Size
2.89 kB
Last Changed
6 months ago
Related

Reactive color mode (dark / light / customs) with auto data persistence.

Demo

← Click to change the color mode

Basic Usage

js
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.

ts
mode.value // 'dark' | 'light'

mode.value = 'dark' // change to dark mode and persist

mode.value = 'auto' // change to auto mode

Config

js
import { useColorMode } from '@vueuse/core'

const mode = useColorMode({
  attribute: 'theme',
  modes: {
    // custom colors
    dim: 'dim',
    cafe: 'cafe',
  },
}) // Ref<'dark' | 'light' | 'dim' | 'cafe'>

Advanced Usage

You can also explicit access to the system preference and storaged user override mode.

js
import { useColorMode } from '@vueuse/core'

const { system, store } = useColorMode()

system.value // 'dark' | 'light'
store.value // 'dark' | 'light' | 'auto'

const myColorMode = computed(() => store.value === 'auto' ? system.value : store.value)

Component Usage

This function also provides a renderless component version via the @vueuse/components package. Learn more about the usage.

vue
<template>
  <UseColorMode v-slot="{ mode }">
    <button @click="mode = mode === 'dark' ? 'light' : 'dark'">
      Mode {{ mode }}
    </button>
  </UseColorMode>
</template>

Type Declarations

Show Type Declarations
typescript
export type BasicColorMode = "light" | "dark"
export type BasicColorSchema = BasicColorMode | "auto"
export interface UseColorModeOptions<T extends string = BasicColorMode>
  extends UseStorageOptions<T | BasicColorMode> {
  /**
   * CSS Selector for the target element applying to
   *
   * @default 'html'
   */
  selector?: string | MaybeElementRef
  /**
   * HTML attribute applying the target element
   *
   * @default 'class'
   */
  attribute?: string
  /**
   * The initial color mode
   *
   * @default 'auto'
   */
  initialValue?: MaybeRefOrGetter<T | BasicColorSchema>
  /**
   * 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 overridden.
   *
   * @default undefined
   */
  onChanged?: (
    mode: T | BasicColorMode,
    defaultHandler: (mode: T | BasicColorMode) => 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
   * @deprecated use `store.value` when `auto` mode needs to be known
   * @see https://vueuse.org/core/useColorMode/#advanced-usage
   */
  emitAuto?: boolean
  /**
   * Disable transition on switch
   *
   * @see https://paco.me/writing/disable-theme-transitions
   * @default true
   */
  disableTransition?: boolean
}
export type UseColorModeReturn<T extends string = BasicColorMode> = Ref<
  T | BasicColorSchema
> & {
  store: Ref<T | BasicColorSchema>
  system: ComputedRef<BasicColorMode>
  state: ComputedRef<T | BasicColorMode>
}
/**
 * Reactive color mode with auto data persistence.
 *
 * @see https://vueuse.org/useColorMode
 * @param options
 */
export declare function useColorMode<T extends string = BasicColorMode>(
  options?: UseColorModeOptions<T>,
): UseColorModeReturn<T>

Source

SourceDemoDocs

Contributors

Anthony Fu
Waleed Khaled
Dominik Freier
wheat
Jason Liang
Yang
丶远方
ntnyq
vaakian X
sun0day
vaakian X
Jelf
Andreas Weber
Andrej Hýll

Changelog

v10.2.0 on 6/16/2023
78a3a - feat: disableTransition support pseudo-elements (#3129)
v10.1.0 on 4/22/2023
a1bef - feat: expose state to the ref, deprecated emitAuto (#2980)
adbbb - fix: element ref support, close #3003
v10.0.0-beta.4 on 4/13/2023
5c82c - fix!: enable disableTransition by default
d150c - feat: expose system and store ref, close #2023
02ccc - feat: support passing element as selector (#2760)
v10.0.0-beta.0 on 3/14/2023
320ab - feat(useDark, useColorMode): introduce disableTransition option
v9.11.0 on 1/17/2023
d5321 - fix(components): mark defineComponent as pure (#2623)
v9.0.1 on 7/29/2022
98f8b - fix: when emitAuto is true, onChanged does not trigger when preferredMode changed (#2004)
v9.0.0-beta.2 on 7/24/2022
fcaf9 - feat: new initialValue option
v8.9.3 on 7/14/2022
499f6 - fix(useStorage)!: rename type StorageOptions to UseStorageOptions (#1867)

Released under the MIT License.