Skip to content
On this page

useDark

Category
Export Size
3.02 kB
Last Changed
3 months ago
Related

Reactive dark mode with auto data persistence.

Demo

Basic Usage

js
import { useDark, useToggle } from '@vueuse/core'

const isDark = useDark()
const toggleDark = useToggle(isDark)
import { useDark, useToggle } from '@vueuse/core'

const isDark = useDark()
const toggleDark = useToggle(isDark)

Behavior

useDarkcombines with usePreferredDarkand useStorage On start up, it reads the value from localStorage/sessionStorage (the key is configurable) to see if there is a user configured color scheme, if not, it will use users' system preferences. When you change the isDark ref, it will update the corresponding element's attribute and then store the preference to storage (default key: vueuse-color-scheme) for persistence.

Please note useDarkonly handles the DOM attribute changes for you to apply proper selector in your CSS. It does NOT handle the actual style, theme or CSS for you.

Configuration

By default, it uses Tailwind CSS favored dark mode, which enables dark mode when class dark is applied to the html tag, for example:

html
<!--light-->
<html> ... </html>

<!--dark-->
<html class="dark"> ... </html>
<!--light-->
<html> ... </html>

<!--dark-->
<html class="dark"> ... </html>

Still, you can also customize it to make it work with most CSS frameworks.

For example:

ts
const isDark = useDark({
  selector: 'body',
  attribute: 'color-scheme',
  valueDark: 'dark',
  valueLight: 'light',
})
const isDark = useDark({
  selector: 'body',
  attribute: 'color-scheme',
  valueDark: 'dark',
  valueLight: 'light',
})

will work like

html
<!--light-->
<html>
  <body color-scheme="light"> ... </body>
</html>

<!--dark-->
<html>
  <body color-scheme="dark"> ... </body>
</html>
<!--light-->
<html>
  <body color-scheme="light"> ... </body>
</html>

<!--dark-->
<html>
  <body color-scheme="dark"> ... </body>
</html>

If the configuration above still does not fit your needs, you can use theonChanged option to take full control over how you handle updates.

ts
const isDark = useDark({
  onChanged(dark: boolean) {
    // update the dom, call the API or something
  },
})
const isDark = useDark({
  onChanged(dark: boolean) {
    // update the dom, call the API or something
  },
})

Component Usage

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

html
<UseDark v-slot="{ isDark, toggleDark }">
  <button @click="toggleDark()">
    Is Dark: {{ isDark }}
  </button>
</UseDark>
<UseDark v-slot="{ isDark, toggleDark }">
  <button @click="toggleDark()">
    Is Dark: {{ isDark }}
  </button>
</UseDark>

Type Declarations

typescript
export interface UseDarkOptions
  extends Omit<UseColorModeOptions<BasicColorSchema>, "modes" | "onChanged"> {
  /**
   * Value applying to the target element when isDark=true
   *
   * @default 'dark'
   */
  valueDark?: string
  /**
   * Value applying to the target element when isDark=false
   *
   * @default ''
   */
  valueLight?: string
  /**
   * A custom handler for handle the updates.
   * When specified, the default behavior will be overridden.
   *
   * @default undefined
   */
  onChanged?: (isDark: boolean) => void
}
/**
 * Reactive dark mode with auto data persistence.
 *
 * @see https://vueuse.org/useDark
 * @param options
 */
export declare function useDark(
  options?: UseDarkOptions
): WritableComputedRef<boolean>
export interface UseDarkOptions
  extends Omit<UseColorModeOptions<BasicColorSchema>, "modes" | "onChanged"> {
  /**
   * Value applying to the target element when isDark=true
   *
   * @default 'dark'
   */
  valueDark?: string
  /**
   * Value applying to the target element when isDark=false
   *
   * @default ''
   */
  valueLight?: string
  /**
   * A custom handler for handle the updates.
   * When specified, the default behavior will be overridden.
   *
   * @default undefined
   */
  onChanged?: (isDark: boolean) => void
}
/**
 * Reactive dark mode with auto data persistence.
 *
 * @see https://vueuse.org/useDark
 * @param options
 */
export declare function useDark(
  options?: UseDarkOptions
): WritableComputedRef<boolean>

Source

SourceDemoDocs

Contributors

Anthony Fu
wheat
Kevin Cole
vaakian X
云游君
Mehran Mirshekaran
Máximo Mussini
Pig Fang
Alex Kozack
ordago
Le Minh Tri

Changelog

v7.1.1 on 11/25/2021
0c4e7 - fix: improve package.json

Released under the MIT License.