click-outside

A tiny, framework-agnostic utility that closes all elements with an .open class when clicking or tapping outside them — just like dropdowns, popovers, and menus do.

✅ Shadow DOM–safe
✅ ESC key support
✅ .co-trigger / ignore selectors
✅ Custom events (will-close-outside / did-close-outside)
✅ Fully typed via JSDoc

📦 Installation

pnpm i @bgunnarsson/click-outside
# or
npm install @bgunnarsson/click-outside
# or
yarn add @bgunnarsson/click-outside

⚙️ Usage

// clickOutside.mjs
import { clickOutside } from 'click-outside-global';

// initialize once at app startup
const dispose = clickOutside({
  openSelector: '.open',        // elements that should close
  triggerSelector: '.co-trigger', // ignore trigger clicks
  escape: true,                 // also close on Escape
});

// later, if you want to stop listening:
dispose();

Example HTML

<button class="co-trigger">Toggle menu</button>

<div class="dropdown open">
  <p>Dropdown content</p>
</div>

When you click anywhere outside .dropdown and not inside .co-trigger,
the .open class will be removed from all elements with .open.

🧠 Custom Events

Each open element emits two events when closing:

| Event | Cancelable | Description | |--------|-------------|-------------| | will-close-outside | ✅ Yes | Fired before removal. Call event.preventDefault() to cancel. | | did-close-outside | ❌ No | Fired after .open was removed. |

Example

document.addEventListener('will-close-outside', (e) => {
  const el = e.target;
  console.log('About to close:', el);

  // Cancel close for sticky elements
  if (el.matches('[data-sticky]')) e.preventDefault();
});

document.addEventListener('did-close-outside', (e) => {
  const el = e.target;
  console.log('Closed:', el);
});

🧩 Options

| Option | Type | Default | Description | |--------|------|----------|-------------| | openSelector | string | '.open' | Selector for open elements. | | triggerSelector | string | – | Selector for elements that should not close when clicked (e.g. .co-trigger). | | ignore | (Element \| string \| (node: Node) => boolean)[] | [] | Additional elements, selectors, or predicates to ignore. | | event | 'pointerdown' \| 'mousedown' \| 'click' | 'pointerdown' | DOM event to listen for. | | escape | boolean | true | Close on Escape key. | | capture | boolean | true | Use capture phase (recommended). | | root | Document \| DocumentFragment | document | Scope for querying open elements. |

🧪 License

MIT © 2025 B. Gunnarsson