useClickOutside()

useClickOutside(reference, handler, debounce?): void

Defined in: hooks/dom/useClickOutside.ts:78

A React hook that invokes a handler when the user clicks or touches outside of the given element.

This is especially useful for:

• Closing dropdowns or select menus when the user clicks elsewhere.
• Dismissing modals, popovers, or sidebars.
• Hiding context menus or tooltips when the user interacts outside.

Internally, this hook:

• Listens to global 'mousedown' and 'touchstart' events.
• Ignores events that originate from inside the referenced element.
• Calls the provided handler once for each qualifying outside interaction.
• Supports optional debouncing via useEventListener.

Parameters

reference

RefObject<HTMLElement | null>

Ref to the target element. Any interaction that happens outside this element will trigger the handler. If reference.current is null, the hook does nothing until the element is mounted.

handler

() => void

Callback to run when an outside click or touch is detected. Typical usage is to close or hide UI, e.g. setOpen(false).

debounce?

number = 0

Debounce delay in milliseconds applied to the underlying event listener.

• 0 or undefined means no debouncing.
• A positive value (e.g. 200) will delay the handler until the user stops interacting for at least that many milliseconds.

Returns

void

Examples

// Close a dropdown when clicking outside

const Dropdown = () => {
  const [open, setOpen] = useState(false);
  const ref = useRef<HTMLDivElement | null>(null);

  useClickOutside(ref, () => setOpen(false));

  return (
    <div>
      <button onClick={() => setOpen((prev) => !prev)}>Toggle</button>
      {open && (
        <div ref={ref}>
          Dropdown content
        </div>
      )}
    </div>
  );
};

// Close a modal with a small debounce to avoid rapid flicker

const Modal = () => {
  const [open, setOpen] = useState(true);
  const modalRef = useRef<HTMLDivElement | null>(null);

  useClickOutside(modalRef, () => setOpen(false), 150);

  if (!open) return null;

  return (
    <div className="backdrop">
      <div ref={modalRef} className="modal">
        Modal content
      </div>
    </div>
  );
};