1---
2category: Utilities
3---
4 
5# useToggle
6 
7A boolean switcher with utility functions.
8 
9## Usage
10 
11```ts
12import { useToggle } from '@vueuse/core'
13 
14const [value, toggle] = useToggle()
15```
16 
17When you pass a ref, `useToggle` will return a simple toggle function instead:
18 
19```ts
20import { useDark, useToggle } from '@vueuse/core'
21 
22const isDark = useDark()
23const toggleDark = useToggle(isDark)
24```
25 
26### Toggle Function
27 
28The toggle function can be called in two ways:
29 
30```ts
31const [value, toggle] = useToggle()
32 
33toggle() // toggle between true and false
34toggle(true) // set to specific value
35 
36// The toggle function returns the new value
37const newValue = toggle() // returns the new value after toggling
38```
39 
40### Custom Values
41 
42You can use custom truthy and falsy values instead of `true` and `false`:
43 
44```ts
45import { useToggle } from '@vueuse/core'
46 
47const [value, toggle] = useToggle('on', {
48  truthyValue: 'on',
49  falsyValue: 'off',
50})
51 
52toggle() // 'off'
53toggle() // 'on'
54```
55 
56The custom values can also be reactive:
57 
58```ts
59import { useToggle } from '@vueuse/core'
60import { ref } from 'vue'
61 
62const truthy = ref('yes')
63const falsy = ref('no')
64 
65const [value, toggle] = useToggle('yes', {
66  truthyValue: truthy,
67  falsyValue: falsy,
68})
69```
70 
71## Caution
72 
73Be aware that the toggle function accepts the first argument as the override value. You might want to avoid directly passing the function to events in the template, as the event object will be passed in.
74 
75```html
76<!-- caution: $event will be passed in -->
77<button @click="toggleDark" />
78<!-- recommended to do this -->
79<button @click="toggleDark()" />
80```
81 
82## Type Declarations
83 
84```ts
85export type ToggleFn = (value?: boolean) => void
86export type UseToggleReturn = [ShallowRef<boolean>, ToggleFn] | ToggleFn
87export interface UseToggleOptions<Truthy, Falsy> {
88  truthyValue?: MaybeRefOrGetter<Truthy>
89  falsyValue?: MaybeRefOrGetter<Falsy>
90}
91export declare function useToggle<Truthy, Falsy, T = Truthy | Falsy>(
92  initialValue: Ref<T>,
93  options?: UseToggleOptions<Truthy, Falsy>,
94): (value?: T) => T
95export declare function useToggle<
96  Truthy = true,
97  Falsy = false,
98  T = Truthy | Falsy,
99>(
100  initialValue?: T,
101  options?: UseToggleOptions<Truthy, Falsy>,
102): [ShallowRef<T>, (value?: T) => T]
103```
104