useClickOutside

Registers a pointerdown listener and calls a handler when the event path does not include any target element. It accepts raw HTMLElement values and Vue component instances.

The listener is created through useEventListener, so it is automatically disposed with the current Vue effect scope when one exists. Call the returned function when manual cleanup is needed. In non-browser contexts, it returns a no-op dispose function.

Importing

import { useClickOutside } from '@almighty-shogun/common';

Usage

<template>
    <aside ref="panel">
        <button @click="close">Close</button>
    </aside>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { useClickOutside } from '@almighty-shogun/common';

const panel = useTemplateRef<HTMLElement>('panel');

function close(): void {
    // Close the panel.
}

useClickOutside(panel, close);
</script>

Parameters

targets: Arrayable<MaybeRefOrGetter<NullableOrUndefinable<ComponentElement>>>
Element, component instance, or array of targets that count as inside the clickable area.

callback: OutsideClickHandler
Handler called for pointerdown events that happen outside every target.

enabled?: MaybeRefOrGetter<boolean>
Reactive flag or getter that controls whether outside clicks are handled.
Default: true

Returns

A dispose function that removes the pointer listener.

Uses

• Arrayable
• NullableOrUndefinable
• Promisable
• unwrapElement
• useEventListener

Type signature

declare function useClickOutside(
    targets: Arrayable<
        MaybeRefOrGetter<NullableOrUndefinable<ComponentElement>>
    >,
    callback: OutsideClickHandler,
    enabled?: MaybeRefOrGetter<boolean>
): UseClickOutside;

type UseClickOutside = () => void;
type ComponentElement = HTMLElement | ComponentPublicInstance;
type OutsideClickHandler = (event: PointerEvent) => Promisable<void>;