1---
2category: Sensors
3---
4 
5# onClickOutside
6 
7Listen for clicks outside of an element. Useful for modals or dropdowns.
8 
9## Usage
10 
11```vue
12<script setup lang="ts">
13import { onClickOutside } from '@vueuse/core'
14import { useTemplateRef } from 'vue'
15 
16const target = useTemplateRef('target')
17 
18onClickOutside(target, event => console.log(event))
19</script>
20 
21<template>
22  <div ref="target">
23    Hello world
24  </div>
25  <div>Outside element</div>
26</template>
27```
28 
29### Return Value
30 
31By default, `onClickOutside` returns a `stop` function to remove the event listeners.
32 
33```ts
34const stop = onClickOutside(target, handler)
35 
36// Later, stop listening
37stop()
38```
39 
40### Controls
41 
42If you need more control over triggering the handler, you can use the `controls` option. This returns an object with `stop`, `cancel`, and `trigger` functions.
43 
44```ts
45const { stop, cancel, trigger } = onClickOutside(
46  modalRef,
47  (event) => {
48    modal.value = false
49  },
50  { controls: true },
51)
52 
53// cancel prevents the next click from triggering the handler
54cancel()
55 
56// trigger manually fires the handler
57trigger(event)
58 
59// stop removes all event listeners
60stop()
61```
62 
63### Ignore Elements
64 
65Use the `ignore` option to prevent certain elements from triggering the handler. Provide elements as an array of Refs or CSS selectors.
66 
67```ts
68const ignoreElRef = useTemplateRef('ignoreEl')
69 
70onClickOutside(
71  target,
72  event => console.log(event),
73  { ignore: [ignoreElRef, '.ignore-class', '#ignore-id'] },
74)
75```
76 
77### Capture Phase
78 
79By default, the event listener uses the capture phase (`capture: true`). Set `capture: false` to use the bubbling phase instead.
80 
81```ts
82onClickOutside(target, handler, { capture: false })
83```
84 
85### Detect Iframe Clicks
86 
87Clicks inside an iframe are not detected by default. Enable `detectIframe` to also trigger the handler when focus moves to an iframe.
88 
89```ts
90onClickOutside(target, handler, { detectIframe: true })
91```
92 
93## Component Usage
94 
95```vue
96<template>
97  <OnClickOutside :options="{ ignore: [/* ... */] }" @trigger="count++">
98    <div>
99      Click Outside of Me
100    </div>
101  </OnClickOutside>
102</template>
103```
104 
105## Directive Usage
106 
107```vue
108<script setup lang="ts">
109import { vOnClickOutside } from '@vueuse/components'
110import { shallowRef } from 'vue'
111 
112const modal = shallowRef(false)
113function closeModal() {
114  modal.value = false
115}
116</script>
117 
118<template>
119  <button @click="modal = true">
120    Open Modal
121  </button>
122  <div v-if="modal" v-on-click-outside="closeModal">
123    Hello World
124  </div>
125</template>
126```
127 
128You can also set the handler as an array to set the configuration items of the instruction.
129 
130```vue
131<script setup lang="ts">
132import { vOnClickOutside } from '@vueuse/components'
133import { shallowRef, useTemplateRef } from 'vue'
134 
135const modal = shallowRef(false)
136 
137const ignoreElRef = useTemplateRef('ignoreEl')
138 
139const onClickOutsideHandler = [
140  (ev) => {
141    console.log(ev)
142    modal.value = false
143  },
144  { ignore: [ignoreElRef] },
145]
146</script>
147 
148<template>
149  <button @click="modal = true">
150    Open Modal
151  </button>
152 
153  <div ref="ignoreElRef">
154    click outside ignore element
155  </div>
156 
157  <div v-if="modal" v-on-click-outside="onClickOutsideHandler">
158    Hello World
159  </div>
160</template>
161```
162 
163## Type Declarations
164 
165```ts
166export interface OnClickOutsideOptions<
167  Controls extends boolean = false,
168> extends ConfigurableWindow {
169  /**
170   * List of elements that should not trigger the event,
171   * provided as Refs or CSS Selectors.
172   */
173  ignore?: MaybeRefOrGetter<(MaybeElementRef | string)[]>
174  /**
175   * Use capturing phase for internal event listener.
176   * @default true
177   */
178  capture?: boolean
179  /**
180   * Run handler function if focus moves to an iframe.
181   * @default false
182   */
183  detectIframe?: boolean
184  /**
185   * Use controls to cancel/trigger listener.
186   * @default false
187   */
188  controls?: Controls
189}
190export type OnClickOutsideHandler<
191  T extends OnClickOutsideOptions<boolean> = OnClickOutsideOptions,
192> = (
193  event:
194    | (T["detectIframe"] extends true ? FocusEvent : never)
195    | (T["controls"] extends true ? Event : never)
196    | PointerEvent,
197) => void
198export type OnClickOutsideReturn<Controls extends boolean = false> =
199  Controls extends false
200    ? Fn
201    : {
202        stop: Fn
203        cancel: Fn
204        trigger: (event: Event) => void
205      }
206/**
207 * Listen for clicks outside of an element.
208 *
209 * @see https://vueuse.org/onClickOutside
210 * @param target
211 * @param handler
212 * @param options
213 */
214export declare function onClickOutside<T extends OnClickOutsideOptions>(
215  target: MaybeComputedElementRef,
216  handler: OnClickOutsideHandler<T>,
217  options?: T,
218): Fn
219export declare function onClickOutside<T extends OnClickOutsideOptions<true>>(
220  target: MaybeComputedElementRef,
221  handler: OnClickOutsideHandler<T>,
222  options: T,
223): {
224  stop: Fn
225  cancel: Fn
226  trigger: (event: Event) => void
227}
228```
229