useOutsideClick
Invokes a callback whenever a click or touch event occurs outside a given element. Ideal for closing dropdowns, modals, or popovers automatically.
When to use it
- Closing a dropdown menu when the user clicks elsewhere on the page.
- Dismissing a modal or tooltip on an outside click/tap.
- Any UI that should collapse when focus moves away from it.
Demo
Open the dropdown, then click anywhere outside of it to close it.
Loading demo…
Signature
function useOutsideClick(
ref: RefObject<HTMLElement>,
callback: () => void
): void;
| Parameter | Type | Description |
|---|---|---|
ref | RefObject<HTMLElement> | Ref of the element to detect outside clicks against. |
callback | () => void | Invoked when a click/touch occurs outside the element. |
Returns: void
Usage notes
- Listens for both
clickandtouchstartevents, so it works well on touch devices too. A single tap fires the callback once, even though the browser also sends an emulatedclickafter the touch. - Always calls the latest
callback, so an inline function is fine and does not re-subscribe the listeners on every render. - Automatically removes its event listeners on unmount.
- The callback fires only when the event target is outside the referenced element (clicks inside it are ignored).
Hook source
View useOutsideClick source
useOutsideClick sourceuse-outside-click.ts
import type { RefObject } from "react";
import { useEffect } from "react";
import { useLatest } from "./use-latest";
/**
* Browsers emulate a `click` shortly after a tap. Clicks within this window of
* a handled `touchstart` are treated as part of the same gesture.
*/
const EMULATED_CLICK_WINDOW_MS = 1000;
/**
* A custom React hook that triggers a callback function when a click or touch event occurs outside the specified element.
*
* This hook is useful for handling scenarios like closing dropdowns, modals, or tooltips when clicking outside the component.
*
* A tap on a touch screen fires the callback once, even though the browser dispatches both a `touchstart` and an emulated `click`. The latest `callback` is always used, so it does not need to be memoized.
*
* @param ref - A React ref object pointing to the element to detect outside clicks for.
* @param callback - The callback function to execute when a click or touch event occurs outside the specified element.
*
* @example
* ```tsx
* const ref = useRef<HTMLDivElement>(null);
* useOutsideClick(ref, () => {
* console.log("Clicked outside the component");
* });
*
* return <div ref={ref}>Click outside this element</div>;
* ```
*
* For a live, editable example, see the [useOutsideClick docs page](https://altalyst-solutions.github.io/hookify/hooks/use-outside-click).
*/
export const useOutsideClick = (
ref: RefObject<HTMLElement | null>,
callback: () => void
): void => {
const callbackRef = useLatest(callback);
useEffect(() => {
let ignoreClicksUntil = -Infinity;
const isOutside = (event: Event) =>
ref.current !== null && !ref.current.contains(event.target as Node);
const handleTouchStart = (event: TouchEvent) => {
if (!isOutside(event)) return;
ignoreClicksUntil = event.timeStamp + EMULATED_CLICK_WINDOW_MS;
callbackRef.current();
};
const handleClick = (event: MouseEvent) => {
if (event.timeStamp <= ignoreClicksUntil) {
ignoreClicksUntil = -Infinity;
return;
}
if (isOutside(event)) callbackRef.current();
};
document.addEventListener("click", handleClick);
document.addEventListener("touchstart", handleTouchStart);
return () => {
document.removeEventListener("click", handleClick);
document.removeEventListener("touchstart", handleTouchStart);
};
}, [ref, callbackRef]);
};