useClickOutside
A composable for detecting clicks outside of specified element(s) with automatic cleanup.
Usage
The useClickOutside composable detects when users click outside target elements. It uses two-phase detection (pointerdown → pointerup) to prevent false positives when dragging, and includes touch scroll handling for mobile.
<script setup lang="ts">
import { useClickOutside } from '@vuetify/v0'
import { shallowRef, useTemplateRef } from 'vue'
const isOpen = shallowRef(false)
const menu = useTemplateRef('menu')
useClickOutside(menu, () => {
isOpen.value = false
})
</script>
<template>
<div ref="menu" class="inline-block">
<button
class="px-4 py-2 bg-primary text-on-primary rounded"
@click="isOpen = !isOpen"
>
{{ isOpen ? 'Close' : 'Open' }} Menu
</button>
<div
v-if="isOpen"
class="absolute mt-2 w-48 py-2 bg-surface border border-divider rounded shadow-lg"
>
<button class="w-full text-left px-4 py-2 text-sm hover:bg-surface-tint">
Profile
</button>
<button class="w-full text-left px-4 py-2 text-sm hover:bg-surface-tint">
Settings
</button>
<button class="w-full text-left px-4 py-2 text-sm hover:bg-surface-tint">
Sign out
</button>
</div>
</div>
</template>
Architecture
useClickOutside builds on useEventListener for pointer and focus event detection:
Reactivity
| Property/Method | Reactive | Notes |
|---|---|---|
isActive | Computed from !isPaused | |
isPaused | ShallowRef, readonly |
Functions
useClickOutside
(target: MaybeArray<ClickOutsideTarget>, handler: (event: PointerEvent | FocusEvent) => void, options?: UseClickOutsideOptions) => UseClickOutsideReturnDetects clicks outside of the specified element(s). Uses two-phase detection (pointerdown → pointerup) to prevent false positives when users drag from inside to outside an element.
Options
capture
booleanUse capture phase for event listeners. Ensures detection works even when inner elements call stopPropagation.
Default: true
touchScrollThreshold
numberTouch movement threshold in pixels. If finger moves more than this distance, it's treated as a scroll, not a tap. Only applies to touch interactions.
Default: 30
detectIframe
booleanDetect focus moving to iframes as an outside click. Useful when iframes are outside the target elements.
Default: false
ignore
MaybeRefOrGetter<ClickOutsideIgnoreTarget[]>Elements to ignore when detecting outside clicks. Accepts element refs, getters, or CSS selector strings. Clicks on these elements (or their descendants) won't trigger the handler. Note: CSS selectors cannot match across Shadow DOM boundaries due to browser limitations. Use element refs instead when ignoring shadow hosts.
bounds
booleanUse bounding rect instead of DOM containment to detect outside clicks. When true, checks if click coordinates are outside the element's bounding box. Useful for native <dialog> elements where backdrop clicks have the dialog as target.
Default: false