toElement

Resolves various element reference types to a plain DOM Element. Accepts refs, getters, raw DOM elements, or Vue component instances and normalizes them to a single Element | undefined.

Copy Markdown

StableIntermediateJun 29, 2026

Usage

import { toElement } from '@vuetify/v0'
import { useTemplateRef } from 'vue'

const el = useTemplateRef<HTMLDivElement>('target')

const element = toElement(el) // HTMLDivElement | undefined

Architecture

toElement resolves multiple input shapes to a DOM element:

Supported Input Types

Input	Result
`Ref<HTMLElement>`	Unwrapped element
`ShallowRef<Element>`	Unwrapped element
`() => HTMLElement`	Called, returns element
`HTMLElement` / `SVGElement`	Pass-through
`ComponentPublicInstance`	Extracts `$el`
`null` / `undefined`	Returns `undefined`

Tip

Structural typing Uses { readonly value: T } instead of Vue’s nominal Ref<T> to avoid type mismatches across Vue versions.

Reactivity

toElement is a pure transformer function. It does not track reactivity or return reactive values.

Tip

Use inside computed for reactivity Wrap in computed() if you need reactive element resolution:

const resolved = computed(() => toElement(targetRef))

An interactive resolver that passes four different input shapes to toElement and displays the resolved element, its tag name, and its id. The Ref button feeds a useTemplateRef — the most common case when working with template refs. Getter wraps the same ref in an arrow function (() => target.value), showing that getters are called and their return value inspected. Raw Element passes target.value directly — already an HTMLElement, so it passes through unchanged. Null demonstrates the graceful undefined return for absent references.

Reach for toElement whenever a composable or utility function accepts a flexible element source — usePopover, useClickOutside, and similar system composables all normalize their target argument through this function internally. The structural { readonly value: T } typing means it accepts refs from any Vue version without nominal type mismatches. Because it is a pure synchronous call, wrap it in toRef(() => toElement(source)) for reactive element tracking that re-resolves whenever the source changes — useful when the target ref may be null initially and populated after mount.