Elements

useParentElement

Returns the parentElement of a target DOM node as a reactive Observable. Re-evaluates whenever the target Ref$ or Observable changes. Targets can be Ref$, MaybeElement, or a plain Element.

Demo

Parent Element

Move your mouse over the page to highlight elements.

current: —parent: —

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 useParentElement: (element?: MaybeEventTarget) => Observable<OpaqueObject<HTMLElement | SVGElement> | null>
useParentElement } 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 parent$: any
parent$ = 
function useParentElement(element?: MaybeEventTarget): Observable<OpaqueObject<HTMLElement | SVGElement> | null>
Framework-agnostic reactive parent-element tracker.
Tracks the parentElement of a DOM node. Accepts Ref$, Observable<Element|null>,
or a raw Element. When the input is a Ref$ or Observable, the parent is
re-read reactively whenever the underlying element reference changes.

NOTE: For a plain (non-Observable) element, the parent is read at construction
time only — subsequent DOM moves are not detected. Use Ref$ or Observable<Element>
for dynamic parent tracking.

Document / Window have no parentElement, so they resolve to null.
@returns ― Observable<OpaqueObject<HTMLElement | SVGElement> | null> — current parent, wrapped opaquely.
useParentElement(
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 parent$: any
parent$.
any
get()?.
any
tagName}</
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>;
}

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

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();
  const parent$ = createParentElement(el$);

  return <div ref={el$}>{parent$.get()?.tagName}</div>;
}

With an Observable target

Hook
Scope

import { observable } from "@usels/core";
import { useParentElement } from "@usels/web";

function Component() {
  const target$ = observable<HTMLElement | null>(null);
  const parent$ = useParentElement(target$);
  // ...
}

import { observable } from "@usels/core";
import { createParentElement } from "@usels/web";

function Component() {
  "use scope"
  const target$ = observable<HTMLElement | null>(null);
  const parent$ = createParentElement(target$);
  // ...
}

With a plain element

A plain (non-Observable) element is read once at construction time; later DOM moves are not detected. Use Ref$ or Observable<Element> for dynamic parent tracking.

Hook
Scope

import { useParentElement } from "@usels/web";

function Component({ el }: { el: HTMLElement }) {
  const parent$ = useParentElement(el);
  // ...
}

import { createParentElement } from "@usels/web";

function Component({ el }: { el: HTMLElement }) {
  "use scope"
  const parent$ = createParentElement(el);
  // ...
}

Type

Parameters

Parameter	Type	Description
`element`	`MaybeEventTarget` (optional)	-

Returns

ObservablePrimitive<OpaqueObject<HTMLElement \| SVGElement> \| null>

Name	Type	Description
`peek`	`{ (): HTMLElement \| SVGElement \| null; (): OpaqueObject<HTMLElement \| SVGElement> \| null; }`	-
`get`	`(trackingType?: TrackingType \| GetOptions) => HTMLElement \| SVGElement \| null`	-
`onChange`	`(cb: ListenerFn<OpaqueObject<HTMLElement \| SVGElement> \| null>, options?: { trackingType?: TrackingType; initial?: boolean \| undefined; immediate?: boolean \| undefined; noArgs?: boolean \| undefined; } \| undefined) => () => void`	-
`set`	`{ (value: (prev: HTMLElement \| SVGElement \| null) => HTMLElement \| SVGElement \| null): void; (value: Observable<HTMLElement \| SVGElement \| null>): void; (value: ImmutableObservableBase<...> \| ... 11 more ... \| null): void; (value: Promise<...>): void; (value: HTMLElement \| ... 1 more ... \| null): void; }`	-
`delete`	`() => void`	-

Source

View on GitHub