Proposal: Separate Component Public Refs from Rendered Element Refs

[nicefan]

This is not primarily about useTemplateRef() ergonomics.

The core issue is that Vue currently uses the same template-ref mechanism for two different concepts:

ref on native element
→ DOM element

ref on component
→ component public instance / defineExpose() result

In Vue 3, especially with <script setup> and defineExpose(), these two concepts are increasingly distinct.

Problem

A component ref is naturally the component's public API:

<MyDialog ref="dialog" />

const dialog = useTemplateRef('dialog')

dialog.value?.open()
dialog.value?.close()

But a parent may also need the component's rendered DOM element for:

ResizeObserver
IntersectionObserver
getBoundingClientRect()
focus()
scrollIntoView()
animation libraries
Floating UI / Popper
drag-and-drop libraries

For example:

<MyButton ref="button" />

If MyButton uses defineExpose():

defineExpose({
  focus,
  reset
})

the parent receives the exposed component API, not a DOM element.

To expose the actual <button>, the child currently has to make an internal template ref part of its public API:

const root = useTemplateRef('root')

defineExpose({
  root
})

This mixes two unrelated concerns:

component public API
and
rendered DOM access

Proposal

Introduce a separate first-class concept for the rendered element of a component.

The exact syntax is not important. For example:

<MyButton
  ref="button"
  element-ref="buttonEl"
/>

Then:

const button = useTemplateRef('button')
const buttonEl = useTemplateRef('buttonEl')

could mean:

button.value
// component public instance / defineExpose() result

buttonEl.value
// HTMLButtonElement | null

Another possible API could be:

<MyButton ref:element="buttonEl" />

or:

const buttonEl = useTemplateElement('button')

The important part is the semantic separation, not the exact API.

Root Resolution

I think element refs could follow rules similar to Vue's existing fallthrough attribute behavior.

Single native root

<template>
  <button />
</template>

The element ref resolves to:

HTMLButtonElement

Single component root

<!-- A.vue -->
<template>
  <B />
</template>

<!-- B.vue -->
<template>
  <button />
</template>

The element ref could follow the unambiguous root chain and resolve to the <button>.

This is conceptually similar to how fallthrough attributes can pass through a component root.

Multiple roots

<template>
  <header />
  <main />
</template>

There is no unambiguous rendered root.

Vue could:

• return null;
• emit a development warning;
• or require the component author to explicitly designate the element.

This is already a familiar concept in Vue because multiple-root components require explicit handling for fallthrough attributes.

Why this matters more in Vue 3

defineExpose() gives components an explicit public interface.

For example:

defineExpose({
  open,
  close,
  reset
})

That API should not need to include an internal DOM ref simply because the parent wants to measure or observe the rendered element.

Conceptually:

Component ref
→ behavior / public interface

Element ref
→ rendering / DOM integration

These are independent capabilities.

Relationship to useTemplateRef()

useTemplateRef() improves how template refs are accessed:

const el = useTemplateRef('foo')

instead of relying on a variable with the same name:

const foo = ref(null)

But it preserves the existing underlying semantics:

native element
→ DOM element

component
→ component public instance

So useTemplateRef() improves ergonomics, but does not address the distinction described here.

Benefits

A separate rendered-element ref would:

• keep defineExpose() focused on the component's actual public API;
• avoid exposing internal template refs only for DOM access;
• make DOM-oriented integrations easier;
• give component refs a more consistent meaning;
• provide a clearer model for Vue's increasingly explicit component encapsulation.

It may also become more useful as Vue evolves rendering modes where component public refs do not necessarily expose $el.

Summary

Vue currently treats these two operations as one template-ref concept:

Get component public API
Get rendered DOM element

I think they should be separate first-class concepts.

A reasonable model could be:

component ref
→ component public interface

element ref
→ unambiguous rendered/root DOM element

with root resolution rules similar to fallthrough attributes:

single unambiguous root
→ resolve automatically

ambiguous multiple roots
→ require explicit handling

This would improve encapsulation while making DOM interoperability easier without overloading the component public API.