Source from repo

VueUse Functions

Apply VueUse composables in Vue 3/Nuxt projects to replace custom implementations with battle-tested utilities.

antfuGitHub antfuSource repo Original GitHub link Publisher page

Files

268

Skill

n/a

Size

631.0 KB

Entrypoint

SKILL.md

Format

git-repo

Open file

references/useDark.md

Syntax-highlighted preview of this file as included in the skill package.

Rendered Source

markdown143 linesFree

references/useDark.md

1---
2category: Browser
3related:
4  - useColorMode
5  - usePreferredDark
6  - useStorage
7---
8 
9# useDark
10 
11Reactive dark mode with auto data persistence.
12 
13<CourseLink href="https://vueschool.io/lessons/theming-with-vueuse-usedark-and-usecolormode?friend=vueuse">Learn useDark with this FREE video lesson from Vue School!</CourseLink>
14 
15## Basic Usage
16 
17```ts
18import { useDark, useToggle } from '@vueuse/core'
19 
20const isDark = useDark()
21const toggleDark = useToggle(isDark)
22```
23 
24## Behavior
25 
26`useDark` combines with `usePreferredDark` and `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.
27 
28> Please note `useDark` only 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.
29 
30## Configuration
31 
32By default, it uses [Tailwind CSS favored dark mode](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually), which enables dark mode when class `dark` is applied to the `html` tag, for example:
33 
34```html
35<!--light-->
36<html>
37  ...
38</html>
39 
40<!--dark-->
41<html class="dark">
42  ...
43</html>
44```
45 
46Still, you can also customize it to make it work with most CSS frameworks.
47 
48For example:
49 
50```ts
51import { useDark } from '@vueuse/core'
52// ---cut---
53const isDark = useDark({
54  selector: 'body',
55  attribute: 'color-scheme',
56  valueDark: 'dark',
57  valueLight: 'light',
58})
59```
60 
61will work like
62 
63```html
64<!--light-->
65<html>
66  <body color-scheme="light">
67    ...
68  </body>
69</html>
70 
71<!--dark-->
72<html>
73  <body color-scheme="dark">
74    ...
75  </body>
76</html>
77```
78 
79If the configuration above still does not fit your needs, you can use the`onChanged` option to take full control over how you handle updates.
80 
81```ts
82import { useDark } from '@vueuse/core'
83// ---cut---
84const isDark = useDark({
85  onChanged(dark) {
86    // update the dom, call the API or something
87  },
88})
89```
90 
91## Component Usage
92 
93```vue
94<template>
95  <UseDark v-slot="{ isDark, toggleDark }">
96    <button @click="toggleDark()">
97      Is Dark: {{ isDark }}
98    </button>
99  </UseDark>
100</template>
101```
102 
103## Type Declarations
104 
105```ts
106export interface UseDarkOptions extends Omit<
107  UseColorModeOptions<BasicColorSchema>,
108  "modes" | "onChanged"
109> {
110  /**
111   * Value applying to the target element when isDark=true
112   *
113   * @default 'dark'
114   */
115  valueDark?: string
116  /**
117   * Value applying to the target element when isDark=false
118   *
119   * @default ''
120   */
121  valueLight?: string
122  /**
123   * A custom handler for handle the updates.
124   * When specified, the default behavior will be overridden.
125   *
126   * @default undefined
127   */
128  onChanged?: (
129    isDark: boolean,
130    defaultHandler: (mode: BasicColorSchema) => void,
131    mode: BasicColorSchema,
132  ) => void
133}
134export type UseDarkReturn = WritableComputedRef<boolean>
135/**
136 * Reactive dark mode with auto data persistence.
137 *
138 * @see https://vueuse.org/useDark
139 * @param options
140 */
141export declare function useDark(options?: UseDarkOptions): UseDarkReturn
142```
143

Preparing the source view

VueUse Functions

references/useDark.md