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 });| Param | Type | Default | Description |
|---|---|---|---|
containerRef | RefObject<T | null> | — | Required. Clicks inside this element are ignored |
listen | boolean | true | Whether the listeners are on. Pass the open state so a closed layer doesn't listen |
onClickAway | () => void | undefined | Called on an outside click or tap, or on Escape |
ignore | Element | null | undefined | Another 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
| Event | Behavior |
|---|---|
mousedown outside | Calls onClickAway, unless the click is inside a layer opened later |
touchend outside | Same as mousedown |
keyup Escape | Calls 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.
useControllableState
One state value that works controlled or uncontrolled, with the value / defaultValue / onChange shape every UnflowUI component uses.
useFocusTrap
Keeps Tab and Shift+Tab inside an element while it is open, and returns focus to where it was on close. Used by ClickAwayEvent and Popper.