useClickOutside
Fire when the user clicks outside a ref.
Import
TypeScript
import { useClickOutside } from '@/hooks';API
Signature
useClickOutside(ref | refs[], handler, events?)
When to use
Dropdowns, popovers, and dismissible panels.
SSR / Next.js
No-ops until document/window exist.
Live playground
Edit the example and see it run against the real @/hooks package in this app.
Live playgroundEdit · run with real
@/hooks · useClickOutsideEditor
function Menu() { const ref = useRef<HTMLDivElement>(null); const [open, setOpen] = useState(false); useClickOutside(ref, () => setOpen(false)); return ( <div> <button onClick={() => setOpen(true)}>Open</button> {open && <div ref={ref}>Menu panel</div>} </div> ); }
Preview
Implementation source
Full library source for useClickOutside — copy into your project when you are not installing a package yet.
hooks/events/useClickOutside.ts
import { useEffect } from 'react';
import type { RefObject } from 'react';
import { isBrowser } from '../utility/isBrowser';
import { useLatest } from '../utility/useLatest';
type Handler = (event: MouseEvent | TouchEvent) => void;
/**
* Invokes handler when a pointer event occurs outside the ref element(s).
*/
export function useClickOutside<T extends HTMLElement>(
ref: RefObject<T | null> | RefObject<T | null>[],
handler: Handler,
events: (keyof DocumentEventMap)[] = ['mousedown', 'touchstart'],
): void {
const handlerRef = useLatest(handler);
useEffect(() => {
if (!isBrowser()) return;
const listener = (event: Event) => {
const refs = Array.isArray(ref) ? ref : [ref];
const target = event.target as Node | null;
if (!target) return;
const isInside = refs.some((r) => r.current && r.current.contains(target));
if (!isInside) {
handlerRef.current(event as MouseEvent | TouchEvent);
}
};
events.forEach((e) => document.addEventListener(e, listener));
return () => {
events.forEach((e) => document.removeEventListener(e, listener));
};
}, [ref, events, handlerRef]);
}
Copy-paste example
useClickOutside.example.tsx
'use client';
import { useRef, useState } from 'react';
import { useClickOutside } from '@/hooks';
export function Menu() {
const ref = useRef<HTMLDivElement>(null);
const [open, setOpen] = useState(false);
useClickOutside(ref, () => setOpen(false));
return (
<div>
<button onClick={() => setOpen(true)}>Open</button>
{open && <div ref={ref}>Menu panel</div>}
</div>
);
}Production checklist
- Called only from Client Components or other custom hooks
- Type parameters filled in (e.g.
useFetch<User[]>) - Tip: Pass all relevant refs to useClickOutside (trigger + panel). Prefer useLatest for handlers.
- Source of truth: open
hooks/events/useClickOutside.tsfor implementation details