useFocusWithin

useFocusWithin(options?)

const [ref, focused] = useFocusWithin<T>(options?);
// <div ref={ref}> …focusable content… </div>

Returns a [ref, focused] tuple:

Element	Type	Description
ref	(node: T | null) => void	A stable callback ref to attach to the container element you want to track.
focused	boolean	true whenever the active element is the container or any descendant. Starts false (also on the server).

T defaults to HTMLElement; pass the concrete element type (e.g. HTMLFormElement) for a precisely-typed ref.

Options — UseFocusWithinOptions

Option	Type	Description
onFocus	(event: FocusEvent) => void	Fires when focus enters a previously-unfocused subtree. Receives the triggering focusin event.
onBlur	(event: FocusEvent) => void	Fires when focus leaves the subtree entirely. Receives the triggering focusout event.

Both callbacks fire only on the edge transitions — moving focus from one descendant to another fires neither.

Also exported

• isFocusInside(container, target) — the reusable predicate for "is this node the container or a descendant of it" (folds in the null cases).
• Types: UseFocusWithinOptions, UseFocusWithinRef, UseFocusWithinReturn.

How focusout is resolved

On focusout the hook decides whether focus truly left the subtree:

1. If event.relatedTarget is a node inside the container → focus just moved between descendants; stay focused.
2. If relatedTarget is a node outside the container → focus left; go false.
3. If relatedTarget is null (unreliable — reported when focus goes to nothing, to another window, or by browsers that omit it) → defer one microtask and re-check document.activeElement; go false only if focus genuinely ended up outside.

Step 3 is what makes the hook robust to the well-known null-relatedTarget quirk while staying fully testable in jsdom.