DOM & Element Utilities

/**
 * Reactive size of an HTML element using ResizeObserver
 * @param target - Target element or ref
 * @param initialSize - Initial size values
 * @param options - Resize observer options
 * @returns Reactive size dimensions and stop function
 */
function useElementSize(
  target: MaybeComputedElementRef,
  initialSize?: ElementSize,
  options?: UseResizeObserverOptions
): {
  width: Ref<number>;
  height: Ref<number>;
  stop: () => void;
};

interface ElementSize {
  width: number;
  height: number;
}

import { ref } from "vue";
import { useElementSize } from "@vueuse/core";

const el = ref<HTMLElement>();
const { width, height } = useElementSize(el);

// In template: <div ref="el">Content</div>
// width and height will update automatically when element resizes

/**
 * Reactive bounding box of an HTML element
 * @param target - Target element or ref
 * @param options - Configuration options
 * @returns Reactive bounding rect properties
 */
function useElementBounding(
  target: MaybeComputedElementRef,
  options?: UseElementBoundingOptions
): {
  x: Ref<number>;
  y: Ref<number>;
  top: Ref<number>;
  right: Ref<number>;
  bottom: Ref<number>;
  left: Ref<number>;
  width: Ref<number>;
  height: Ref<number>;
  update: () => void;
  stop: () => void;
};

interface UseElementBoundingOptions {
  reset?: boolean;
  windowResize?: boolean;
  windowScroll?: boolean;
  immediate?: boolean;
}

/**
 * Track element visibility using IntersectionObserver
 * @param element - Target element or ref
 * @param options - Intersection observer options
 * @param scrollTarget - Custom scroll container
 * @returns Reactive visibility state
 */
function useElementVisibility(
  element: MaybeComputedElementRef,
  options?: IntersectionObserverInit,
  scrollTarget?: MaybeComputedElementRef
): Ref<boolean>;

/**
 * Reactive element hover state
 * @param el - Target element or ref
 * @param options - Configuration options
 * @returns Reactive hover state
 */
function useElementHover(
  el: MaybeComputedElementRef,
  options?: UseElementHoverOptions
): Ref<boolean>;

interface UseElementHoverOptions {
  delayEnter?: number;
  delayLeave?: number;
}

/**
 * Reactive document.activeElement
 * @param options - Configuration options
 * @returns Reactive active element ref
 */
function useActiveElement<T extends HTMLElement>(
  options?: UseActiveElementOptions
): ShallowRef<T | null | undefined>;

interface UseActiveElementOptions extends ConfigurableWindow, ConfigurableDocument {
  deep?: boolean;
  triggerOnRemoval?: boolean;
}

/**
 * Get current component's root element
 * @returns Reactive ref to current component element
 */
function useCurrentElement<T extends Element = Element>(): ComputedRef<T | undefined>;

/**
 * Track and control element focus state
 * @param target - Target element or ref
 * @param options - Configuration options
 * @returns Focus state and control functions
 */
function useFocus(
  target: MaybeComputedElementRef,
  options?: UseFocusOptions
): UseFocusReturn;

interface UseFocusReturn {
  focused: Ref<boolean>;
  focus: () => void;
  blur: () => void;
}

interface UseFocusOptions {
  initialValue?: boolean;
  focusVisible?: boolean;
}

/**
 * Track if focus is within an element
 * @param target - Target element or ref
 * @param options - Configuration options
 * @returns Reactive focus within state
 */
function useFocusWithin(
  target: MaybeComputedElementRef,
  options?: UseFocusWithinOptions
): UseFocusWithinReturn;

interface UseFocusWithinReturn {
  focused: Ref<boolean>;
}

/**
 * Check if component is mounted
 * @returns Reactive mounted state
 */
function useMounted(): Ref<boolean>;

/**
 * Get DOM element from ref or Vue component instance
 * @param elRef - Element ref or Vue component instance
 * @returns DOM element or null
 */
function unrefElement<T extends Element = Element>(
  elRef: MaybeComputedElementRef<T>
): T | null | undefined;

type MaybeElement = HTMLElement | SVGElement | VueInstance | undefined | null;

type MaybeElementRef<T extends Element = Element> = MaybeRef<T | null | undefined>;

type MaybeComputedElementRef<T extends Element = Element> = MaybeRefOrGetter<T | null | undefined>;

/**
 * Get parent element of current element
 * @param element - Target element or ref
 * @returns Reactive parent element ref
 */
function useParentElement(
  element?: MaybeComputedElementRef
): ComputedRef<Element | null | undefined>;

/**
 * Get element at specific coordinates using document.elementFromPoint
 * @param x - X coordinate (reactive)
 * @param y - Y coordinate (reactive)
 * @param options - Configuration options
 * @returns Reactive element at point
 */
function useElementByPoint(
  x: MaybeRefOrGetter<number>,
  y: MaybeRefOrGetter<number>,
  options?: UseElementByPointOptions
): ComputedRef<Element | null>;

interface UseElementByPointOptions extends ConfigurableDocument {
  multiple?: boolean;
}

/**
 * @deprecated Use Vue's built-in useTemplateRef instead
 * Shorthand for binding ref to template element
 * @param key - Template ref key
 * @param initialValue - Initial value
 * @returns Template ref
 */
function templateRef<T extends Element | null>(
  key: string,
  initialValue?: T | null
): Readonly<Ref<T>>;

/**
 * Shorthand for binding array of refs to template
 * @param key - Template ref key
 * @returns Array of template refs
 */
function useTemplateRefsList<T = Element>(): readonly [
  Readonly<Ref<readonly T[]>>,
  (el: T | null) => void
];

/**
 * Listen for element removal from DOM
 * @param target - Target element or ref
 * @param callback - Callback when element is removed
 * @param options - Mutation observer options
 * @returns Stop function
 */
function onElementRemoval(
  target: MaybeElementRef,
  callback: () => void,
  options?: MutationObserverInit
): (() => void) | undefined;

/**
 * SSR-safe width measurement
 * @param element - Target element or ref
 * @param initialWidth - Initial width for SSR
 * @returns Reactive width value
 */
function useSSRWidth(
  element: MaybeComputedElementRef,
  initialWidth?: number
): Ref<number>;

/**
 * Reactive ResizeObserver utility
 * @param target - Target element(s) or ref(s)
 * @param callback - Resize callback function
 * @param options - Resize observer options
 * @returns Observer utilities
 */
function useResizeObserver(
  target: MaybeComputedElementRef | MaybeComputedElementRef[],
  callback: ResizeObserverCallback,
  options?: UseResizeObserverOptions
): {
  isSupported: ComputedRef<boolean>;
  stop: () => void;
};

interface UseResizeObserverOptions extends ConfigurableWindow {
  box?: ResizeObserverBoxOptions;
}

/**
 * Reactive IntersectionObserver utility
 * @param target - Target element(s) or ref(s)
 * @param callback - Intersection callback function
 * @param options - Intersection observer options
 * @returns Observer utilities with pause/resume
 */
function useIntersectionObserver(
  target: MaybeElementRef | MaybeElementRef[],
  callback: IntersectionObserverCallback,
  options?: UseIntersectionObserverOptions
): UseIntersectionObserverReturn;

interface UseIntersectionObserverReturn {
  isSupported: Ref<boolean>;
  stop: () => void;
  pause: () => void;
  resume: () => void;
}

/**
 * Reactive MutationObserver utility
 * @param target - Target element or ref to observe
 * @param callback - Mutation callback function
 * @param options - Mutation observer options
 * @returns Observer utilities
 */
function useMutationObserver(
  target: MaybeElementRef,
  callback: MutationCallback,
  options?: MutationObserverInit
): {
  isSupported: Ref<boolean>;
  stop: () => void;
};