UnflowUI
ComponentsHooks

useClickAway

Calls a callback when the user clicks or taps outside an element, or presses Escape. Used by ClickAwayEvent and Popper.

Overview

useClickAway closes floating UI (menus, popovers, inline editors) when the user clicks or taps outside an element or presses Escape. It attaches the listeners to the element you pass, so no wrapper element is needed.

It powers ClickAwayEvent and Popper. Use the component when a wrapper div is fine, and the hook when the element that owns the behaviour already exists.

Import

import { useClickAway } from '@unflowio/ui/hooks/useClickAway';

Parameters

useClickAway(containerRef, { listen, onClickAway, ignore });
ParamTypeDefaultDescription
containerRefRefObject<T | null>—Required. Clicks inside this element are ignored
listenbooleantrueWhether the listeners are on. Pass the open state so a closed layer doesn't listen
onClickAway() => voidundefinedCalled on an outside click or tap, or on Escape
ignoreElement | nullundefinedAnother element whose clicks also count as inside, typically the trigger button

Return value

None.

Usage

import { useCallback, useRef, useState } from 'react';
import { useClickAway } from '@unflowio/ui/hooks/useClickAway';

function InlineMenu() {
  const [open, setOpen] = useState(false);
  const [trigger, setTrigger] = useState<HTMLButtonElement | null>(null);
  const menuRef = useRef<HTMLDivElement>(null);
  const close = useCallback(() => setOpen(false), []);

  useClickAway(menuRef, { listen: open, onClickAway: close, ignore: trigger });

  return (
    <>
      <button ref={setTrigger} aria-expanded={open} onClick={() => setOpen((o) => !o)}>
        Options
      </button>
      {open && (
        <div ref={menuRef} role="menu">
          …
        </div>
      )}
    </>
  );
}

Pass the trigger as ignore. Otherwise a click on it counts as outside: the menu closes on mousedown and the button's onClick opens it again.

Events

EventBehavior
mousedown outsideCalls onClickAway, unless the click is inside a layer opened later
touchend outsideSame as mousedown
keyup EscapeCalls onClickAway on the topmost layer only, wherever focus is

Implementation notes

Stacked layers. Every listening hook joins one shared stack, in the order it starts listening; a parent and a child that start together are ordered parent first. Escape closes only the topmost layer, so a menu inside a modal closes before the modal. A click inside a layer opened later counts as inside every layer below it, even when that layer is portalled outside their containers. A click outside all of them closes them all.

Callbacks. onClickAway and ignore are read when an event fires, so inline callbacks are fine and changing them keeps the layer's place in the stack. Keep ignore in state (as above) rather than reading ref.current during render.

Accessibility

Closing on Escape meets the expectation for dismissible popups. When the popup closes, move focus back to its trigger if focus was inside it, or pair the hook with useFocusTrap, which restores focus for you.