An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file useClickableContainer.ts
* @input Container ref, interactive element ref, click/href handlers
* @output onClick, onMouseUp and onPointerDown handlers for the container;
* INTERACTIVE_SELECTORS list; hasInteractiveAncestor and the shared
* innermostInteractive walk; the internal useClickableContainerProxy, the
* handlers without the marker
* @position Core hook for clickable containers with nested interactive
* elements. A click on a nested button or link does not run the card's
* action, and a finger press there shows no press on the card. Each navigation
* passes the rule in utils/safeUrl.ts first.
*
* SYNC: When modified, update:
* - /packages/core/src/hooks/index.ts (export)
*/
import {
useCallback,
useEffect,
type RefObject,
type MouseEvent,
type PointerEvent,
} from 'react';
import {isLayerSurface} from '../Layer/layerSurfacePress';
import {isSafeUrl} from '../utils/safeUrl';
import {cancelPress} from '../utils/pressFeedback';
/**
* The attribute this hook sets on the container it makes clickable. A click
* inside a nested marked container belongs to that container (see
* INTERACTIVE_SELECTORS).
*/
export const PRESSABLE_CONTAINER_ATTRIBUTE = 'data-pressable-container';
/**
* Canonical list of interactive element selectors — native controls plus
* role-based interactive elements. Clicks on these (or their descendants)
* should NOT bubble to a clickable container's click handler.
*
* Exported so other focus/interaction utilities can share one comprehensive
* definition of "interactive target" rather than hand-rolling divergent lists.
* Note: this list is about "don't bubble clicks", not focus-eligibility —
* consumers that need focusable elements must additionally exclude
* unfocusable/disabled targets (e.g. `[tabindex="-1"]`, `:disabled`).
*/
export const INTERACTIVE_SELECTORS = [
'button',
'a',
'input',
'select',
'textarea',
'[role="button"]',
'[role="link"]',
'[role="checkbox"]',
'[role="radio"]',
'[role="switch"]',
'[role="tab"]',
'[role="menuitem"]',
'[role="option"]',
'[role="combobox"]',
'[role="listbox"]',
'[role="slider"]',
'[role="spinbutton"]',
`[${PRESSABLE_CONTAINER_ATTRIBUTE}]`,
].join(',');
const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';
/**
* Whether this element is interactive by INTERACTIVE_SELECTORS: a control,
* link, editor, or nested clickable container, and not marked read-only.
*/
export function matchesInteractiveSelectors(element: Element): boolean {
return (
element.matches(INTERACTIVE_SELECTORS) &&
!element.matches(NON_INTERACTIVE_SELECTORS)
);
}
/**
* The innermost element, from `el` up to (not including) `rootEl` or the
* document body, that `isInteractive` accepts: by default the
* INTERACTIVE_SELECTORS match. The one walk every "does this event belong
* to a control" check shares; a hover layer's tap passes its own test
* (useTouchTrigger's `tapLandsOnDisabledControl`).
*/
export function innermostInteractive(
el: Element,
rootEl: Element | null,
isInteractive: (element: Element) => boolean = matchesInteractiveSelectors,
): Element | null {
let current: Element | null = el;
while (current != null && current !== rootEl && current !== document.body) {
if (isInteractive(current)) {
return current;
}
current = current.parentElement;
}
return null;
}
/**
* Check whether an element has an interactive ancestor between it and the
* root (the element itself included). If the click target is inside a nested
* button/link/etc., we should NOT handle it at the container level.
*
* Exported for containers that cannot use the hook itself — a `<tr>` whose
* props are assembled inside a Table plugin's `transformBodyRow`, for
* instance, has no ref to hand the hook but needs the identical rule. Sharing
* the walk keeps one definition of "this click belongs to something else"
* instead of a short hand-rolled selector list per caller.
*
* A press inside an open Tooltip or HoverCard surface also answers true: it
* belongs to that surface, not the container around its trigger.
*/
export function hasInteractiveAncestor(el: Element, rootEl: Element): boolean {
return innermostInteractive(el, rootEl, belongsToSomethingElse) != null;
}
// hasInteractiveAncestor documents this answer until the next minor.
// A layer root stops such a press before any bubble-phase React handler.
// A native listener or a capture-phase handler still sees it.
function belongsToSomethingElse(element: Element): boolean {
return matchesInteractiveSelectors(element) || isLayerSurface(element);
}
/**
* The touch half of a container's press rule: a finger press that starts on a nested interactive element
* other than the container's own action does not activate the container, so
* it ends the press controller's paint on `container`. A mouse or pen press,
* and a press on the container's surface or on `ownAction`, are left alone.
* Not part of the package's public API.
*/
export function cancelNestedTouchPress(
event: PointerEvent<HTMLElement>,
container: HTMLElement | null,
ownAction: Element | null,
): void {
const target = event.target;
if (
event.pointerType !== 'touch' ||
container == null ||
!(target instanceof Element) ||
target === event.currentTarget ||
!hasInteractiveAncestor(target, container) ||
// The container's own action, such as the control it delegates to: a
// press on it activates the container.
ownAction?.contains(target) === true
) {
return;
}
cancelPress(container);
}
/**
* Check if there's a text selection inside the node (don't navigate on text select)
*
* Exported alongside {@link hasInteractiveAncestor} for the same reason: a
* click that ends a text drag is not a click on the container, and every
* clickable surface needs that rule, hook or no hook. Scoped to the node, so a
* selection somewhere else on the page does not make the surface inert.
*/
export function hasTextSelection(node: Element): boolean {
if (typeof document === 'undefined' || !('getSelection' in document)) {
return false;
}
const selection = document.getSelection();
if (selection == null || selection.isCollapsed) {
return false;
}
return node.contains(selection.anchorNode);
}
export interface UseClickableContainerOptions {
/** Ref to the outer container element */
containerRef: RefObject<HTMLElement | null>;
/** Ref to the primary interactive element inside (link, button) */
interactiveRef?: RefObject<HTMLElement | null>;
/** Click handler */
onClick?: (event: MouseEvent<HTMLElement>) => void;
/**
* Navigation URL — when provided, clicking the container navigates. Checked
* with the shared navigation rule (utils/safeUrl.ts) before any activation
* method (plain, new-tab, Cmd/Ctrl-click, middle-click, delegated click).
*/
href?: string;
/** Link target */
target?: string;
/** Whether the container is disabled */
disabled?: boolean;
}
export interface ClickableContainerResult {
onClick: (event: MouseEvent<HTMLElement>) => void;
onMouseUp: (event: MouseEvent<HTMLElement>) => void;
/**
* Spread on the container with `onClick`. A press that starts on a nested
* interactive element does not activate the container. On a container that
* paints its press with `usePressFeedback`, this drops that touch press.
* A mouse `:active` press paint is unchanged. A container without it keeps
* its activation rule and shows its pressed state for every press.
*/
onPointerDown: (event: PointerEvent<HTMLElement>) => void;
}
/**
* Hook that makes a container element clickable while preserving
* nested interactive element behavior.
*
* When the user clicks the container surface (not on a nested button/link),
* the hook fires the onClick handler or navigates to href.
* When the user clicks a nested interactive element, it does nothing —
* the nested element handles its own event.
*
* @compositionHint Use inside ClickableCard or SelectableCard.
* For custom interactive containers, pair with a ref to the outer div.
*
* @example
* ```
* const containerRef = useRef<HTMLDivElement>(null);
* const { onClick, onMouseUp, onPointerDown } = useClickableContainer({
* containerRef,
* onClick: () => console.log('card clicked'),
* });
* return (
* <div
* ref={containerRef}
* onClick={onClick}
* onMouseUp={onMouseUp}
* onPointerDown={onPointerDown}>
* <p>Click anywhere on this card</p>
* <button onClick={() => alert('button')}>Nested button</button>
* </div>
* );
* ```
*/
export function useClickableContainer(
options: UseClickableContainerOptions,
): ClickableContainerResult {
const {containerRef} = options;
// Mark container as pressable for the interactive selector check
useEffect(() => {
const el = containerRef.current;
if (el) {
el.setAttribute(PRESSABLE_CONTAINER_ATTRIBUTE, 'true');
}
}, [containerRef]);
return useClickableContainerProxy(options);
}
/**
* `useClickableContainer`'s click handlers, without its marker. Internal: Item
* serves its delegate and List link rows from one call, and renders the marker
* on a delegate row itself.
*/
export function useClickableContainerProxy({
containerRef,
interactiveRef,
onClick: onClickProp,
href,
target,
disabled = false,
}: UseClickableContainerOptions): ClickableContainerResult {
const onClick = useCallback(
(event: MouseEvent<HTMLElement>) => {
if (disabled) {
return;
}
const containerEl = containerRef.current;
if (!containerEl) {
return;
}
if (hasTextSelection(containerEl)) {
return;
}
const eventTarget = event.target;
if (!(eventTarget instanceof Element)) {
return;
}
if (
eventTarget !== event.currentTarget &&
hasInteractiveAncestor(eventTarget, containerEl)
) {
return;
}
onClickProp?.(event);
if (event.defaultPrevented) {
return;
}
// React DOM checks the hrefs that it writes, but nothing below passes
// through React. So the shared navigation rule decides once, before the
// target, a modifier key, or the delegated anchor picks a sink. A
// blocked href does not navigate, but the click handler above still ran.
if (href != null && isSafeUrl(href)) {
const shouldOpenNewTab =
target === '_blank' || event.ctrlKey || event.metaKey;
if (shouldOpenNewTab) {
window.open(href, '_blank', 'noopener');
} else if (interactiveRef?.current) {
// Proxy click to the sr-only link so the framework link component
// handles navigation (client-side transitions in Next.js, etc.).
interactiveRef.current.click();
} else {
// eslint-disable-next-line react-compiler/react-compiler -- browser navigation API
window.location.href = href;
}
}
// Proxy click to the interactive ref if no explicit handler
if (href == null && onClickProp == null && interactiveRef?.current) {
const clickEvent = new MouseEvent('click', {
bubbles: event.bubbles,
cancelable: event.cancelable,
ctrlKey: event.ctrlKey,
metaKey: event.metaKey,
shiftKey: event.shiftKey,
altKey: event.altKey,
button: event.button,
});
interactiveRef.current.dispatchEvent(clickEvent);
event.stopPropagation();
}
},
[containerRef, interactiveRef, onClickProp, href, target, disabled],
);
const onMouseUp = useCallback(
(event: MouseEvent<HTMLElement>) => {
if (disabled) {
return;
}
const containerEl = containerRef.current;
if (!containerEl) {
return;
}
const eventTarget = event.target;
if (!(eventTarget instanceof Element)) {
return;
}
// Middle-click on href opens in new tab (same scheme rule as onClick —
// this navigation never passes through React either).
const isMiddleClick = event.button === 1;
if (
isMiddleClick &&
href != null &&
isSafeUrl(href) &&
(eventTarget === event.currentTarget ||
!hasInteractiveAncestor(eventTarget, containerEl))
) {
window.open(href, '_blank', 'noopener');
}
},
[containerRef, href, disabled],
);
// The press-state counterpart of onClick's rule, for touch: a finger press
// that would not activate the container shows no press on it. A mouse or
// pen press keeps its `:active` paint.
const onPointerDown = useCallback(
(event: PointerEvent<HTMLElement>) => {
if (disabled) {
return;
}
cancelNestedTouchPress(
event,
containerRef.current,
interactiveRef?.current ?? null,
);
},
[containerRef, interactiveRef, disabled],
);
return {onClick, onMouseUp, onPointerDown};
}