useActivator
Commons
stable
Wire an activator element (button, link, any DOM node) to an overlay component. Manages click, hover, focus, and context-menu open strategies, delay scheduling, and cursor-position targeting. Used internally by Menu, Tooltip, Dialog, and every component that needs a trigger-controlled overlay.
API
Signature
Full TypeScript signature sourced from the composable file.
useActivator is a low-level primitive used by all overlay components. For most cases, prefer <OrigamMenu>, <OrigamTooltip>, or <OrigamDialog> which consume it internally.
Consumed interfaces
IActivatorProps
IDelayProps
API
Parameters
Input parameters accepted by this composable.
- propsrequiredIActivatorProps
- Props controlling how the overlay is triggered. Includes activator selector/element, open-on strategy (click, hover, focus, context-menu), close-on-content-click, delay settings inherited from IDelayProps, and an optional target override.
- isActiverequiredRef<boolean>
- Reactive flag representing the open/closed state of the overlay. useActivator reads and writes this ref to toggle the overlay on user interaction.
- isToprequiredRef<boolean>
- Reactive flag set by the overlay stack manager. When true, this overlay is the topmost one; when it becomes false while hover/focus-triggered, the composable auto-closes the overlay.
API
Return values
Properties and methods exposed by the composable return object.
- activatorEl
- The resolved activator DOM element. Updated on each user interaction event so the overlay can position itself relative to the correct element.
- activatorRef
- Template ref for a statically rendered activator child. Assign to the activator element via v-bind to let the composable resolve it automatically on mount.
- target
- Resolved positioning target. Returns cursor coordinates when target="cursor" is set, the element bound to targetRef when provided, or falls back to the activatorEl.
- targetEl
- Target as a plain HTMLElement (undefined when target is a coordinate pair). Useful for anchor-positioning calculations that require an element.
- targetRef
- Template ref for an explicit positioning target element, independent from the activator element.
- activatorEvents
- Event listeners to spread on the activator element via v-bind. Only includes listeners relevant to the active open strategy (onClick, onMouseenter/leave, onFocus/Blur, onContextmenu).
- contentEvents
- Event listeners to spread on the overlay content panel. Handles hover-sustain (keep open while cursor is inside the content), focus-in/out relay, and closeOnContentClick.
- scrimEvents
- Event listeners for the backdrop scrim element. Sustains hover-open when the cursor moves from the activator to the scrim before reaching the content.
Usage
Examples
Ready-to-paste usage snippets.
Click-triggered overlay
Hover-triggered tooltip