unrefElement#

Resolve a flexible element target to the raw DOM element (or null). The primitive every DOM-attaching composable uses to accept refs, signals, getters, and plain elements interchangeably. Browser composable — import from @sigx/use-web.

TypeScript 
import { signal } from 'sigx';
import { unrefElement } from '@sigx/use-web';

const el = signal<HTMLElement | null>(null);
// <div ref={el}> …

unrefElement(el);              // the raw <div>, or null before mount
unrefElement(() => document.body); // getter form
unrefElement(someElement);     // passed straight through

It accepts every shape in the element-target convention: a raw element or EventTarget, a getter, a branded sigx handle (a PrimitiveSignal, a computed, or a toSignal/toSignals view), or a sigx template-ref { current } object — the shape sigx's JSX ref prop writes into. Reading a reactive handle tracks, so a watcher calling unrefElement re-runs when the element changes.

Detection is brand-based (isSignal/isComputed), so an arbitrary plain { value } object is not unwrapped. If you hold an element in a plain object, pass it as a getter (() => obj.value).

The result is passed through toRaw: reactive object-signal reads wrap elements in proxies, and raw identity is what removeEventListener pairing, observer bookkeeping, and native element methods require.

Signature#

TypeScript 
function unrefElement<T extends EventTarget = EventTarget>(
    target:
        | MaybeSignalElement
        | T
        | ReadSignal<T | null | undefined>
        | { current: T | null | undefined }
        | (() => T | null | undefined)
        | null
        | undefined,
): T | null;

See also#