EventIntermediateBrowser APIshooks/events/useClickOutside.ts

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 · useClickOutside
Editor
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.ts for implementation details