useOnClickOutside

Handle clicks outside specified elements with support for multiple refs and event types. Perfect for React applications requiring modal and dropdown behavior with Next.js integration and TypeScript support.

Loading component...

"use client";import React, { useRef, useState } from 'react';import { useOnClickOutside } from '@/components/ui/shadcn-io/use-on-click-outside';export default function UseOnClickOutsideDemo() {  const [isOpen, setIsOpen] = useState(false);  const [clickCount, setClickCount] = useState({ inside: 0, outside: 0 });  const targetRef = useRef<HTMLDivElement>(null);  const handleClickOutside = () => {    setClickCount(prev => ({ ...prev, outside: prev.outside + 1 }));    if (isOpen) {      setIsOpen(false);    }  };  const handleClickInside = () => {    setClickCount(prev => ({ ...prev, inside: prev.inside + 1 }));    if (!isOpen) {      setIsOpen(true);    }  };  useOnClickOutside(targetRef as React.RefObject<HTMLElement>, handleClickOutside);  return (    <div className="flex flex-col items-center justify-center min-h-[300px] p-8 space-y-6">      {/* Status Display */}      <div className="text-center space-y-2">        <h3 className="text-lg font-semibold">Click Outside Detection</h3>        <div className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${          isOpen             ? "bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-300"             : "bg-gray-100 text-gray-800 dark:bg-gray-800 dark:text-gray-300"        }`}>          Target: {isOpen ? '🟢 Active' : '🔴 Inactive'}        </div>      </div>      {/* Interactive Target */}      <div         ref={targetRef}        onClick={handleClickInside}        className={`          w-48 h-32 rounded-lg cursor-pointer transition-all duration-200          border-2 border-dashed flex items-center justify-center text-center          ${isOpen             ? 'border-green-400 bg-green-50 dark:bg-green-900/20 scale-105'             : 'border-gray-300 bg-gray-50 dark:bg-gray-800 hover:border-gray-400'          }        `}      >        <div>          <div className="text-2xl mb-2">{isOpen ? '🎯' : '📍'}</div>          <div className="text-sm font-medium">            {isOpen ? 'Click outside to close' : 'Click me to activate'}          </div>          <div className="text-xs text-muted-foreground mt-1">            Target Element          </div>        </div>      </div>      {/* Click Statistics */}      <div className="grid grid-cols-2 gap-4 text-center">        <div className="px-4 py-2 bg-muted rounded-lg">          <div className="text-lg font-bold text-green-600">            {clickCount.inside}          </div>          <div className="text-xs text-muted-foreground">Inside Clicks</div>        </div>        <div className="px-4 py-2 bg-muted rounded-lg">          <div className="text-lg font-bold text-blue-600">            {clickCount.outside}          </div>          <div className="text-xs text-muted-foreground">Outside Clicks</div>        </div>      </div>      {/* Instructions */}      <div className="text-center text-sm text-muted-foreground max-w-md">        <p>Click the target element to activate it, then click anywhere outside to deactivate.</p>        <p className="mt-1">The hook detects clicks outside the specified element.</p>      </div>    </div>  );}

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-on-click-outside.json

npx shadcn@latest add https://www.shadcn.io/registry/use-on-click-outside.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-on-click-outside.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-on-click-outside.json

Features

Multiple element support allowing monitoring of single ref or array of refs
Flexible event types supporting mouse, touch, and focus events for comprehensive interaction
TypeScript generics with type-safe element references and event handling
Event listener options supporting passive listeners and capture phase control
Performance optimized using useEventListener with proper cleanup and delegation
shadcn/ui integration ideal for dropdown menus, modals, and popup components

Examples

Multiple Elements with Event Types

Loading component...

"use client";import * as React from "react";import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useOnClickOutside } from "@/components/ui/shadcn-io/use-on-click-outside";export default function UseOnClickOutsideAdvancedDemo() {  const [activeElements, setActiveElements] = React.useState<Set<number>>(new Set());  const [eventType, setEventType] = React.useState<'mousedown' | 'mouseup'>('mousedown');  const [outsideClickCount, setOutsideClickCount] = React.useState(0);    const element1Ref = React.useRef<HTMLDivElement>(null);  const element2Ref = React.useRef<HTMLDivElement>(null);  const element3Ref = React.useRef<HTMLDivElement>(null);  // Handle clicks outside all elements  const handleOutsideClick = React.useCallback(() => {    setActiveElements(new Set());    setOutsideClickCount(prev => prev + 1);  }, []);  // Use the hook with multiple refs  useOnClickOutside(    [element1Ref, element2Ref, element3Ref] as React.RefObject<HTMLElement>[],    handleOutsideClick,    eventType  );  const toggleElement = (id: number) => {    setActiveElements(prev => {      const newSet = new Set(prev);      if (newSet.has(id)) {        newSet.delete(id);      } else {        newSet.add(id);      }      return newSet;    });  };  const elements = [    { id: 1, ref: element1Ref, color: 'blue', label: 'Element 1' },    { id: 2, ref: element2Ref, color: 'green', label: 'Element 2' },    { id: 3, ref: element3Ref, color: 'purple', label: 'Element 3' },  ];  return (    <div className="space-y-3 p-4 max-w-sm mx-auto">      {/* Configuration */}      <div className="space-y-2">        <div className="flex items-center justify-between">          <Label className="text-sm font-medium">Multiple Elements</Label>          <Badge variant="secondary" className="text-xs">            {outsideClickCount} outside clicks          </Badge>        </div>                <div className="flex gap-2">          <Button            onClick={() => setEventType('mousedown')}            variant={eventType === 'mousedown' ? 'default' : 'outline'}            size="sm"            className="flex-1 h-7 text-xs"          >            mousedown          </Button>          <Button            onClick={() => setEventType('mouseup')}            variant={eventType === 'mouseup' ? 'default' : 'outline'}            size="sm"            className="flex-1 h-7 text-xs"          >            mouseup          </Button>        </div>      </div>      {/* Interactive Elements */}      <div className="space-y-2">        <Label className="text-sm font-medium">Click Elements</Label>        <div className="space-y-2">          {elements.map(({ id, ref, color, label }) => (            <div              key={id}              ref={ref}              onClick={() => toggleElement(id)}              className={`                p-3 rounded border-2 cursor-pointer transition-all text-center text-sm                ${activeElements.has(id)                  ? `border-${color}-400 bg-${color}-50 dark:bg-${color}-900/20 scale-105`                  : 'border-gray-300 bg-gray-50 dark:bg-gray-800 hover:border-gray-400'                }              `}            >              <div className="font-medium">{label}</div>              <div className="text-xs text-muted-foreground mt-1">                {activeElements.has(id) ? 'Active' : 'Click to activate'}              </div>            </div>          ))}        </div>      </div>      {/* Status Grid */}      <div className="space-y-2">        <Label className="text-sm font-medium">Element Status</Label>        <div className="grid grid-cols-3 gap-1 text-xs">          {elements.map(({ id, label }) => (            <div               key={id}              className={`p-1.5 rounded text-center ${                activeElements.has(id)                   ? 'bg-blue-100 dark:bg-blue-900'                   : 'bg-muted'              }`}            >              {label.split(' ')[1]}              <div className="text-[10px] text-muted-foreground">                {activeElements.has(id) ? 'ON' : 'OFF'}              </div>            </div>          ))}        </div>      </div>      {/* Summary */}      <div className="space-y-2">        <Label className="text-sm font-medium">Summary</Label>        <div className="p-2 bg-muted rounded text-xs space-y-1">          <div className="flex justify-between">            <span>Active:</span>            <span>{activeElements.size}/3</span>          </div>          <div className="flex justify-between">            <span>Event:</span>            <span>{eventType}</span>          </div>          <div className="flex justify-between">            <span>Outside clicks:</span>            <span>{outsideClickCount}</span>          </div>        </div>      </div>      {/* Instructions */}      <div className="text-xs text-muted-foreground text-center">        Click elements to activate, then click outside to clear all      </div>    </div>  );}

import * as React from "react"import { Slot } from "@radix-ui/react-slot"import { cva, type VariantProps } from "class-variance-authority"import { cn } from "@/lib/utils"const buttonVariants = cva(  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",  {    variants: {      variant: {        default:          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",        destructive:          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",        outline:          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",        secondary:          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",        ghost:          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",        link: "text-primary underline-offset-4 hover:underline",      },      size: {        default: "h-9 px-4 py-2 has-[>svg]:px-3",        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",        icon: "size-9",      },    },    defaultVariants: {      variant: "default",      size: "default",    },  })function Button({  className,  variant,  size,  asChild = false,  ...props}: React.ComponentProps<"button"> &  VariantProps<typeof buttonVariants> & {    asChild?: boolean  }) {  const Comp = asChild ? Slot : "button"  return (    <Comp      data-slot="button"      className={cn(buttonVariants({ variant, size, className }))}      {...props}    />  )}export { Button, buttonVariants }

Advanced configuration with multiple elements and different event type handling.

Use Cases

This free open source React component works well for:

Modal dialogs - Close modals when clicking outside with Next.js and TypeScript
Dropdown menus - Hide dropdowns on outside clicks using shadcn/ui components
Context menus - Dismiss right-click menus with Tailwind CSS styling
Tooltip management - Auto-hide tooltips when focus moves elsewhere

API Reference

Parameter	Type	Default	Description
`ref`	`RefObject<T> \| RefObject<T>[]`	required	Single ref or array of refs to monitor
`handler`	`(event) => void`	required	Callback fired when clicking outside element(s)
`eventType`	`EventType`	`'mousedown'`	Event type to listen for
`eventListenerOptions`	`AddEventListenerOptions`	`{}`	Native event listener options

Event Types

Type	Description
`'mousedown'`	Mouse button pressed (default)
`'mouseup'`	Mouse button released
`'touchstart'`	Touch interaction begins
`'touchend'`	Touch interaction ends
`'focusin'`	Element receives focus
`'focusout'`	Element loses focus

Event Listener Options

Option	Type	Description
`passive`	`boolean`	Passive event listener for performance
`capture`	`boolean`	Capture events in capture phase
`once`	`boolean`	Remove listener after first trigger

Usage Patterns

Single Element

import { useOnClickOutside } from '@repo/use-on-click-outside';

function Modal({ onClose }) {
  const modalRef = useRef(null);
  
  useOnClickOutside(modalRef, onClose);
  
  return <div ref={modalRef}>Modal content</div>;
}

Multiple Elements

const [menu1Ref, menu2Ref] = [useRef(null), useRef(null)];

useOnClickOutside([menu1Ref, menu2Ref], () => {
  setMenusOpen(false);
});

Custom Event Type

useOnClickOutside(ref, handler, 'touchstart', { passive: true });

Implementation Notes

Automatically filters refs with null current values for safety
Checks event target connectivity to prevent stale reference issues
Works with both single refs and ref arrays for complex UI patterns
Compatible with React portals and dynamically rendered content
Supports all AddEventListenerOptions for fine-tuned event handling
Integrates seamlessly with useEventListener for consistent behavior

useOnClickOutside

Reactbutton

Reactbadge

Reactlabel

On this page