Elements

useMouseInElement

Tracks the mouse cursor position relative to a DOM element and reports whether the cursor is inside or outside it. Observes mousemove, document mouseleave, ResizeObserver, MutationObserver (style/class attribute changes), and window scroll/resize events to keep values accurate as the element moves or resizes. All return values are reactive Observable<number | boolean>.

Demo

Mouse in Element

Move your mouse over the box to track position.

elementX

0px

elementY

0px

isOutside

true

width

0px

height

0px

x (global)

0px

move your mouse here

import { 
const useRef$: {
    <T = any>(initialValue: null): Ref$<T | null>;
    <T = any>(initialValue: T): Ref$<T>;
    <T = any>(): Ref$<T | null>;
}
useRef$ } from "@usels/core";
import { 
const useMouseInElement: (target: MaybeEventTarget, options?: DeepMaybeObservable<UseMouseInElementOptions>) => UseMouseInElementReturn
useMouseInElement } from "@usels/web";

function 
function Component(): JSX.Element
Component() {
  const 
const el$: Ref$<HTMLDivElement | null>
el$ = 
useRef$<HTMLDivElement>(): Ref$<HTMLDivElement | null> (+2 overloads)
Core (framework-agnostic) version of useRef$.
Creates an observable element ref with opaque wrapping.

non-null value → Ref$<T>: current, get(), peek() return T
null / no arg → Ref$<T | null>: current, get(), peek() return T | null

Nullability is expressed via the type parameter, mirroring T | null at the call site.
useRef$<
interface HTMLDivElement
HTMLDivElement>();
  const { 
const elementX$: any
Mouse X position relative to the element
elementX$, 
const elementY$: any
Mouse Y position relative to the element
elementY$, 
const isOutside$: any
Whether the mouse is outside the element
isOutside$ } = 
function useMouseInElement(target: MaybeEventTarget, options?: DeepMaybeObservable<UseMouseInElementOptions>): UseMouseInElementReturn
Framework-agnostic mouse-in-element tracker. Must be called inside a
useScope factory — mousemove, mouseleave, window scroll/resize
listeners as well as ResizeObserver / MutationObserver for the target are
all registered via the scope-aware create* helpers and cleaned up
automatically when the scope disposes. Public API matches the legacy
useMouseInElement hook.
useMouseInElement(
const el$: Ref$<HTMLDivElement | null>
el$);

  return (
    <
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div 
RefAttributes<HTMLDivElement>.ref?: Ref<HTMLDivElement> | undefined
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref).
@see ― https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs
ref={
const el$: Ref$<HTMLDivElement | null>
el$}>
      {
const isOutside$: any
Whether the mouse is outside the element
isOutside$.
any
get() ? "outside" : `${
const elementX$: any
Mouse X position relative to the element
elementX$.
any
get()}, ${
const elementY$: any
Mouse Y position relative to the element
elementY$.
any
get()}`}
    </
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>
  );
}

import { createRef$ } from "@usels/core";
import { createMouseInElement } from "@usels/web";

function Component() {
  "use scope";
  const el$ = createRef$<HTMLDivElement>();
  const { elementX$, elementY$, isOutside$ } = createMouseInElement(el$);

  return (
    <div ref={el$}>
      {isOutside$.get() ? "outside" : `${elementX$.get()}, ${elementY$.get()}`}
    </div>
  );
}

Disable outside tracking

By default elementX$/elementY$ continue to update even when the cursor leaves the element. Pass handleOutside: false to freeze the last in-element position once the cursor exits.

const { elementX$, elementY$ } = useMouseInElement(el$, { handleOutside: false });

Disable scroll / resize recalculation

const { elementX$, elementY$ } = useMouseInElement(el$, {
  windowScroll: false,
  windowResize: false,
});

Stop all observers manually

// @noErrors
import { useRef$, Ref$ } from "@usels/core";
import { useMouseInElement } from "@usels/web";
declare const el$: Ref$<HTMLDivElement>;
// ---cut---
const { elementX$, elementY$, stop } = useMouseInElement(el$);

// Tear down all event listeners and observers
stop();

Global mouse coordinates

The raw clientX / clientY values are also exposed as x$ and y$.

// @noErrors
import { useRef$, Ref$ } from "@usels/core";
import { useMouseInElement } from "@usels/web";
declare const el$: Ref$<HTMLDivElement>;
// ---cut---
const { x$, y$, elementX$, elementY$ } = useMouseInElement(el$);

Type

Parameters

Parameter	Type	Description
`target`	`MaybeEventTarget`	-
`options`	`UseMouseInElementOptions` (optional)	-

UseMouseInElementOptions

Option	Type	Default	Description
`handleOutside`	`boolean`	`-`	Also update elementX/Y when mouse is outside the element. Default: true
`windowScroll`	`boolean`	`-`	Re-calculate on window scroll. Default: true
`windowResize`	`boolean`	`-`	Re-calculate on window resize. Default: true
`window`	`WindowSource`	`-`	-

Returns

UseMouseInElementReturn

Name	Type	Description
`elementX$`	`ObservablePrimitive<number>`	Mouse X position relative to the element
`elementY$`	`ObservablePrimitive<number>`	Mouse Y position relative to the element
`elementPositionX$`	`ObservablePrimitive<number>`	Element’s absolute X position on the page
`elementPositionY$`	`ObservablePrimitive<number>`	Element’s absolute Y position on the page
`elementWidth$`	`ObservablePrimitive<number>`	Element width
`elementHeight$`	`ObservablePrimitive<number>`	Element height
`isOutside$`	`ObservableBoolean<boolean>`	Whether the mouse is outside the element
`x$`	`ObservablePrimitive<number>`	Global mouse X (clientX)
`y$`	`ObservablePrimitive<number>`	Global mouse Y (clientY)
`stop`	`() => void`	Stop all observers and event listeners

Source

View on GitHub