on-click-outside

Call a handler when the user clicks (or focuses an iframe) outside an element.


Package	`@vizejs/composable/on-click-outside`
Own the source	`vize lib pull composable:on-click-outside`
Runtime exports	`onClickOutside`
Gzip budget	2816 B

Usage

import { onClickOutside } from "@vizejs/composable/on-click-outside";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`onClickOutside`	events	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`globalThis`, `window`	`resolveElement`, `tryOnScopeDispose`

API

`onClickOutside`

Call a handler when the user clicks (or focuses an iframe) outside an element. A click counts as outside only when its pointerdown also started outside the target, so drags that begin inside (e.g. text selection) and end outside are ignored. Event paths (composedPath()) make shadow-DOM targets work. The host is resolved once, when called. Nothing is registered during server rendering; listeners are removed with the owning scope or by the returned stop function.

function onClickOutside( target: MaybeElementTarget, handler: (event: Event) => void, options: OnClickOutsideOptions = {}, ): () => void

Types

`ClickOutsideHost`

Window-like capability observed by onClickOutside.

Member	Type	Description
`document`	`{ readonly activeElement: Element \| null }`	Document used to detect focus moving into an iframe.

`OnClickOutsideOptions`

Options for onClickOutside.

Member	Type	Description
`ignore`?	`MaybeRefOrGetter<readonly ClickOutsideIgnore[]>`	Elements (or selectors) whose clicks never count as outside, e.g. the button that toggles a popover.
`capture`?	`boolean`	Listen in the capture phase so `stopPropagation()` inside the page cannot hide outside clicks.
`detectIframe`?	`boolean`	Treat focus moving into an `<iframe>` outside the target as an outside click (iframes swallow pointer events).
`scheduler`?	`TimeoutScheduler`	Owns the zero-delay timer used for iframe detection.
`host`?	`MaybeRefOrGetter<ClickOutsideHost \| null \| undefined>`	Reactive window capability for alternate runtimes and tests.