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 { useTemplateRef } from 'vue'
const menu = useTemplateRef('menu')
useClickOutside(menu, () => {
console.log('Clicked outside the menu')
})
</script>
<template>
<div ref="menu">
Menu content
</div>
</template>Architecture
useClickOutside builds on useEventListener for pointer and focus event detection:
Multiple Targets
Pass an array of refs to ignore clicks inside any of them:
import { useClickOutside } from '@vuetify/v0'
import { useTemplateRef } from 'vue'
const trigger = useTemplateRef('trigger')
const panel = useTemplateRef('panel')
// Clicks inside EITHER trigger or panel are ignored
useClickOutside([trigger, panel], () => {
console.log('Clicked outside both elements')
})The target parameter accepts MaybeArray<ClickOutsideTarget> — a single ref/getter or an array of refs/getters.
Options
| Option | Type | Default | Description |
|---|---|---|---|
bounds | boolean | false | Use bounding-rect detection instead of DOM containment. Required for native <dialog> elements — backdrop clicks have the <dialog> as the event target, so containment checks always pass |
import { useClickOutside } from '@vuetify/v0'
const dialog = useTemplateRef('dialog')
// For native <dialog> — backdrop clicks are detected via coordinates
useClickOutside(dialog, () => dialog.value?.close(), { bounds: true })Reactivity
| Property/Method | Reactive | Notes |
|---|---|---|
isActive | Computed from !isPaused | |
isPaused | ShallowRef, readonly | |
pause() | - | Stop detection, preserve state |
resume() | - | Resume detection |
stop() | - | Stop and clean up listeners |
Examples
Dropdown with Outside Dismiss
A dropdown menu that opens on button click and automatically closes when clicking anywhere outside the menu.
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
boolean | undefinedUse capture phase for event listeners. Ensures detection works even when inner elements call stopPropagation.
Default: true
touchScrollThreshold
number | undefinedTouch 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
boolean | undefinedDetect focus moving to iframes as an outside click. Useful when iframes are outside the target elements.
Default: false
ignore
MaybeRefOrGetter<ClickOutsideIgnoreTarget[]> | undefinedElements 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
boolean | undefinedUse 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