use-click-outside (use-click-outside)

Detects clicks outside of a referenced element.

v0.1.0

Usage

import { use-click-outside } from "@/hooks"

"use client";

import React, { useRef, useState } from "react";

import { Button } from "@/components/ui/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";

import { useClickOutside } from "@/components/hooks/use-click-outside";

export function UseClickOutsideDemo() {
  const cardRef = useRef<HTMLDivElement>(null);
  const [clickedOutside, setClickedOutside] = useState(false);

  useClickOutside(cardRef, () => {
    setClickedOutside(true);
  });

  return (
    <Card ref={cardRef} className="w-full max-w-sm relative">
      <CardHeader>
        <CardTitle>useClickOutside</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <p className="text-sm">
          Click outside of the card to trigger an action.
        </p>
        {clickedOutside ? (
          <div className="text-red-500 font-semibold mb-2">
            You clicked outside of the card!
          </div>
        ) : null}
        <Button onClick={() => setClickedOutside(false)} variant="outline">
          Reset
        </Button>
      </CardContent>
    </Card>
  );
}

Install

npx wkkkis-hooks add use-click-outside

Options

Name	Type	Default	Description
ref	RefObject	null	The reference to the element to detect clicks outside of
onClickOutside	function	null	The function to call when a click outside the element occurs

Event Types & Capturing

Listens for both mousedown and touchstart events to detect clicks and touches outside the referenced element.
Listeners are attached in the capturing phase (ensuring early detection before event bubbling).

Callback Reference

The callback is always up-to-date using a ref, so you can safely use inline or dynamic functions without worrying about stale closures or unnecessary re-attachments.

Behavior

The callback is only called if the event target is outside the referenced element.
If the ref is null or the event target is not a DOM node, the callback is not called.

Cleanup

Event listeners are automatically removed when the component unmounts.

Caveats & Best Practices

Works for clicks/touches outside the referenced element, including those in React portals.
Not suitable for server-side rendering (SSR) directly, as it uses document .
If you use multiple refs or dynamic elements, ensure the ref is stable and points to the correct element.
The hook does not distinguish between left, right, or middle mouse buttons.

Files in this hook

Source	Destination
files/use-click-outside.ts	src/hooks/use-click-outside.ts