react-click-guard

A lightweight, dependency-free React utility to detect clicks outside an element. Perfect for closing modals, dropdowns, tooltips, and popovers.

Why?

• 📦 Zero Dependencies: Pure React & JS.
• 🪶 Tiny: ~500 bytes gzipped.
• 🖱️ Smart: Handles mousedown and touchstart by default (works on mobile).
• ⚛️ Flexible: Provides both a Hook and a Component.

Installation

npm install react-click-guard
# or
yarn add react-click-guard

Usage

1. Using the Component (ClickGuard)

The easiest way to wrap a section of your UI.

import { useState } from 'react';
import { ClickGuard } from 'react-click-guard';

function Dropdown() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="relative">
      <button onClick={() => setIsOpen(!isOpen)}>Toggle Menu</button>
      
      {isOpen && (
        <ClickGuard onClickOutside={() => setIsOpen(false)} className="menu-container">
          <div className="menu">
            <p>Menu Item 1</p>
            <p>Menu Item 2</p>
          </div>
        </ClickGuard>
      )}
    </div>
  );
}

2. Using the Hook (useClickOutside)

For when you need direct control over the ref.

import { useRef, useState } from 'react';
import { useClickOutside } from 'react-click-guard';

function Modal() {
  const modalRef = useRef(null);
  const [isOpen, setIsOpen] = useState(true);

  // Close when clicking outside the modal content
  useClickOutside(modalRef, () => {
    setIsOpen(false);
  });

  if (!isOpen) return null;

  return (
    <div className="overlay">
      <div ref={modalRef} className="modal-content">
        <h2>Modal Title</h2>
        <p>Click outside this box to close me.</p>
      </div>
    </div>
  );
}

API

<ClickGuard />

| Prop | Type | Default | Description | |------|------|---------|-------------| | onClickOutside | () => void | required | Callback fired when a click happens outside. | | as | string \| Component | 'div' | The element to render as the wrapper. | | enabled | boolean | true | Enable/disable the listener conditionally. | | events | string[] | ['mousedown', 'touchstart'] | DOM events to listen for. |

useClickOutside(ref, callback, options)

| Argument | Type | Description | |----------|------|-------------| | ref | React.RefObject | The element ref to detect clicks outside of. | | callback | (event) => void | Function to call on outside click. | | options | { enabled?: boolean, events?: string[] } | Configuration object. |

License

MIT