0
# DOM & Element Utilities
1

2
Reactive utilities for interacting with DOM elements, tracking element properties, managing element state, and handling element lifecycle.
3

4
## Capabilities
5

6
### Element Properties
7

8
#### useElementSize
9

10
Reactive size tracking of HTML elements using ResizeObserver.
11

12
```typescript { .api }
13
/**
14
 * Reactive size of an HTML element using ResizeObserver
15
 * @param target - Target element or ref
16
 * @param initialSize - Initial size values
17
 * @param options - Resize observer options
18
 * @returns Reactive size dimensions and stop function
19
 */
20
function useElementSize(
21
  target: MaybeComputedElementRef,
22
  initialSize?: ElementSize,
23
  options?: UseResizeObserverOptions
24
): {
25
  width: Ref<number>;
26
  height: Ref<number>;
27
  stop: () => void;
28
};
29

30
interface ElementSize {
31
  width: number;
32
  height: number;
33
}
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
import { ref } from "vue";
40
import { useElementSize } from "@vueuse/core";
41

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

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

49
#### useElementBounding
50

51
Reactive bounding box of an HTML element.
52

53
```typescript { .api }
54
/**
55
 * Reactive bounding box of an HTML element
56
 * @param target - Target element or ref
57
 * @param options - Configuration options
58
 * @returns Reactive bounding rect properties
59
 */
60
function useElementBounding(
61
  target: MaybeComputedElementRef,
62
  options?: UseElementBoundingOptions
63
): {
64
  x: Ref<number>;
65
  y: Ref<number>;
66
  top: Ref<number>;
67
  right: Ref<number>;
68
  bottom: Ref<number>;
69
  left: Ref<number>;
70
  width: Ref<number>;
71
  height: Ref<number>;
72
  update: () => void;
73
  stop: () => void;
74
};
75

76
interface UseElementBoundingOptions {
77
  reset?: boolean;
78
  windowResize?: boolean;
79
  windowScroll?: boolean;
80
  immediate?: boolean;
81
}
82
```
83

84
#### useElementVisibility
85

86
Track element visibility using IntersectionObserver.
87

88
```typescript { .api }
89
/**
90
 * Track element visibility using IntersectionObserver
91
 * @param element - Target element or ref
92
 * @param options - Intersection observer options
93
 * @param scrollTarget - Custom scroll container
94
 * @returns Reactive visibility state
95
 */
96
function useElementVisibility(
97
  element: MaybeComputedElementRef,
98
  options?: IntersectionObserverInit,
99
  scrollTarget?: MaybeComputedElementRef
100
): Ref<boolean>;
101
```
102

103
#### useElementHover
104

105
Reactive element hover state tracking.
106

107
```typescript { .api }
108
/**
109
 * Reactive element hover state
110
 * @param el - Target element or ref
111
 * @param options - Configuration options
112
 * @returns Reactive hover state
113
 */
114
function useElementHover(
115
  el: MaybeComputedElementRef,
116
  options?: UseElementHoverOptions
117
): Ref<boolean>;
118

119
interface UseElementHoverOptions {
120
  delayEnter?: number;
121
  delayLeave?: number;
122
}
123
```
124

125
### Element State
126

127
#### useActiveElement
128

129
Reactive tracking of document.activeElement.
130

131
```typescript { .api }
132
/**
133
 * Reactive document.activeElement
134
 * @param options - Configuration options
135
 * @returns Reactive active element ref
136
 */
137
function useActiveElement<T extends HTMLElement>(
138
  options?: UseActiveElementOptions
139
): ShallowRef<T | null | undefined>;
140

141
interface UseActiveElementOptions extends ConfigurableWindow, ConfigurableDocument {
142
  deep?: boolean;
143
  triggerOnRemoval?: boolean;
144
}
145
```
146

147
#### useCurrentElement
148

149
Get current component's root element.
150

151
```typescript { .api }
152
/**
153
 * Get current component's root element
154
 * @returns Reactive ref to current component element
155
 */
156
function useCurrentElement<T extends Element = Element>(): ComputedRef<T | undefined>;
157
```
158

159
#### useFocus
160

161
Track and control element focus state.
162

163
```typescript { .api }
164
/**
165
 * Track and control element focus state
166
 * @param target - Target element or ref
167
 * @param options - Configuration options
168
 * @returns Focus state and control functions
169
 */
170
function useFocus(
171
  target: MaybeComputedElementRef,
172
  options?: UseFocusOptions
173
): UseFocusReturn;
174

175
interface UseFocusReturn {
176
  focused: Ref<boolean>;
177
  focus: () => void;
178
  blur: () => void;
179
}
180

181
interface UseFocusOptions {
182
  initialValue?: boolean;
183
  focusVisible?: boolean;
184
}
185
```
186

187
#### useFocusWithin
188

189
Track if focus is within an element (element or any of its children).
190

191
```typescript { .api }
192
/**
193
 * Track if focus is within an element
194
 * @param target - Target element or ref
195
 * @param options - Configuration options
196
 * @returns Reactive focus within state
197
 */
198
function useFocusWithin(
199
  target: MaybeComputedElementRef,
200
  options?: UseFocusWithinOptions
201
): UseFocusWithinReturn;
202

203
interface UseFocusWithinReturn {
204
  focused: Ref<boolean>;
205
}
206
```
207

208
#### useMounted
209

210
Check if component is mounted.
211

212
```typescript { .api }
213
/**
214
 * Check if component is mounted
215
 * @returns Reactive mounted state
216
 */
217
function useMounted(): Ref<boolean>;
218
```
219

220
### Element Utilities
221

222
#### unrefElement
223

224
Get DOM element from ref or Vue component instance.
225

226
```typescript { .api }
227
/**
228
 * Get DOM element from ref or Vue component instance
229
 * @param elRef - Element ref or Vue component instance
230
 * @returns DOM element or null
231
 */
232
function unrefElement<T extends Element = Element>(
233
  elRef: MaybeComputedElementRef<T>
234
): T | null | undefined;
235

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

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

240
type MaybeComputedElementRef<T extends Element = Element> = MaybeRefOrGetter<T | null | undefined>;
241
```
242

243
#### useParentElement
244

245
Get parent element of current element.
246

247
```typescript { .api }
248
/**
249
 * Get parent element of current element
250
 * @param element - Target element or ref
251
 * @returns Reactive parent element ref
252
 */
253
function useParentElement(
254
  element?: MaybeComputedElementRef
255
): ComputedRef<Element | null | undefined>;
256
```
257

258
#### useElementByPoint
259

260
Get element at specific coordinates.
261

262
```typescript { .api }
263
/**
264
 * Get element at specific coordinates using document.elementFromPoint
265
 * @param x - X coordinate (reactive)
266
 * @param y - Y coordinate (reactive)
267
 * @param options - Configuration options
268
 * @returns Reactive element at point
269
 */
270
function useElementByPoint(
271
  x: MaybeRefOrGetter<number>,
272
  y: MaybeRefOrGetter<number>,
273
  options?: UseElementByPointOptions
274
): ComputedRef<Element | null>;
275

276
interface UseElementByPointOptions extends ConfigurableDocument {
277
  multiple?: boolean;
278
}
279
```
280

281
### Template Utilities
282

283
#### templateRef
284

285
**DEPRECATED** - Use Vue's built-in `useTemplateRef` instead.
286

287
```typescript { .api }
288
/**
289
 * @deprecated Use Vue's built-in useTemplateRef instead
290
 * Shorthand for binding ref to template element
291
 * @param key - Template ref key
292
 * @param initialValue - Initial value
293
 * @returns Template ref
294
 */
295
function templateRef<T extends Element | null>(
296
  key: string,
297
  initialValue?: T | null
298
): Readonly<Ref<T>>;
299
```
300

301
#### useTemplateRefsList
302

303
Shorthand for binding array of refs to template.
304

305
```typescript { .api }
306
/**
307
 * Shorthand for binding array of refs to template
308
 * @param key - Template ref key
309
 * @returns Array of template refs
310
 */
311
function useTemplateRefsList<T = Element>(): readonly [
312
  Readonly<Ref<readonly T[]>>,
313
  (el: T | null) => void
314
];
315
```
316

317
### Element Lifecycle
318

319
#### onElementRemoval
320

321
Listen for element removal from DOM.
322

323
```typescript { .api }
324
/**
325
 * Listen for element removal from DOM
326
 * @param target - Target element or ref
327
 * @param callback - Callback when element is removed
328
 * @param options - Mutation observer options
329
 * @returns Stop function
330
 */
331
function onElementRemoval(
332
  target: MaybeElementRef,
333
  callback: () => void,
334
  options?: MutationObserverInit
335
): (() => void) | undefined;
336
```
337

338
### SSR Utilities
339

340
#### useSSRWidth
341

342
SSR-safe width measurement utility.
343

344
```typescript { .api }
345
/**
346
 * SSR-safe width measurement
347
 * @param element - Target element or ref
348
 * @param initialWidth - Initial width for SSR
349
 * @returns Reactive width value
350
 */
351
function useSSRWidth(
352
  element: MaybeComputedElementRef,
353
  initialWidth?: number
354
): Ref<number>;
355
```
356

357
### Observers
358

359
#### useResizeObserver
360

361
Reactive ResizeObserver utility.
362

363
```typescript { .api }
364
/**
365
 * Reactive ResizeObserver utility
366
 * @param target - Target element(s) or ref(s)
367
 * @param callback - Resize callback function
368
 * @param options - Resize observer options
369
 * @returns Observer utilities
370
 */
371
function useResizeObserver(
372
  target: MaybeComputedElementRef | MaybeComputedElementRef[],
373
  callback: ResizeObserverCallback,
374
  options?: UseResizeObserverOptions
375
): {
376
  isSupported: ComputedRef<boolean>;
377
  stop: () => void;
378
};
379

380
interface UseResizeObserverOptions extends ConfigurableWindow {
381
  box?: ResizeObserverBoxOptions;
382
}
383
```
384

385
#### useIntersectionObserver
386

387
Reactive IntersectionObserver utility.
388

389
```typescript { .api }
390
/**
391
 * Reactive IntersectionObserver utility
392
 * @param target - Target element(s) or ref(s)
393
 * @param callback - Intersection callback function
394
 * @param options - Intersection observer options
395
 * @returns Observer utilities with pause/resume
396
 */
397
function useIntersectionObserver(
398
  target: MaybeElementRef | MaybeElementRef[],
399
  callback: IntersectionObserverCallback,
400
  options?: UseIntersectionObserverOptions
401
): UseIntersectionObserverReturn;
402

403
interface UseIntersectionObserverReturn {
404
  isSupported: Ref<boolean>;
405
  stop: () => void;
406
  pause: () => void;
407
  resume: () => void;
408
}
409
```
410

411
#### useMutationObserver
412

413
Reactive MutationObserver utility for watching DOM changes.
414

415
```typescript { .api }
416
/**
417
 * Reactive MutationObserver utility
418
 * @param target - Target element or ref to observe
419
 * @param callback - Mutation callback function
420
 * @param options - Mutation observer options
421
 * @returns Observer utilities
422
 */
423
function useMutationObserver(
424
  target: MaybeElementRef,
425
  callback: MutationCallback,
426
  options?: MutationObserverInit
427
): {
428
  isSupported: Ref<boolean>;
429
  stop: () => void;
430
};
431
```