Concerns around useTemplateRef and an alternative design

[NonSpicyBurrito]

Related: vuejs/rfcs#427, 3ba70e4

3.5.0-alpha.3 added useTemplateRef, which I'd like to bring up some concerns around its current design.

Take the following code example:

<script setup lang="ts">
const foo = useTemplateRef<HTMLDivElement>('my_div')
</script>

<template>
    <img ref="my_img" />
</template>

There are a few issues with this code:

• In setup, the ref key is my_div, yet in template the ref key is my_img by mistake.
• In setup, the ref type is HTMLDivElement, yet in template it's a HTMLImageElement.
• IDE features such as rename symbol, find references, will be poor or simply impossible.

Some of the issues above can potentially be solved by having special analysis around the usage of useTemplateRef, however that only helps in the most trivial cases, and any layer of indirection will break those analysis. For example:

function useMyTemplateRef<T>(key: string) {
    return useTemplateRef<T>(key)
}

<script setup lang="ts">
const foo = useMyTemplateRef<HTMLDivElement>('my_div')
</script>

<template>
    <img ref="my_img" />
</template>

Instead, a potential alternative design could be:

• A helper templateRef<T>() which is equivalent to ref<T | null>(null).
• Improvements to tooling such that the existing ref="foo" syntax is linked back to the foo variable.
• Type checking of the existing ref="foo" syntax.

<script setup lang="ts">
const foo = templateRef<HTMLDivElement>()
</script>

<template>
    <img ref="bar" />
</template>

This will solve the above issues:

• In setup, foo can be statically analyzed to warn for not used anywhere. In template, ref="bar" can be statically analyzed to warn for bar not existing.
• In template, type checking can be performed on ref="foo" to see that the ref type of HTMLDivElement does not match the template type HTMLImageElement.
• IDE can link ref="foo" in template to foo in setup, which allows features such as rename symbol, find references, etc.
• Layers of indirection will not break the above analysis and features.

I believe that the current useTemplateRef design hurts the ability to statically analyze to catch problems at compile time and the ability to provide rich tooling features, and an alternative design is worth looking into.

[hubdidub]

I always found it weird that a variable name had to match with the value of a some attribute down in the <template> section. That's why I really like the current useTemplateRef function.

But if it hurts tooling capabilities (which I can't judge), I guess that's a really good point.

[NonSpicyBurrito]

I always found it weird that a variable name had to match with the value of a some attribute down in the <template> section.

If I had to guess, it would be related to progressive enhancement aspect of Vue and is now kept the same API for backwards compatibility. Ideally, ref should work the same way as v-model.
The current useTemplateRef effectively relies on magic strings to connect two pieces of logic in template and script. My concern is that while useTemplateRef is a slight improvement to the current situation in terms of readability, it does not solve the fundamental magic string issues with ref. If Vue is going to eventually add a better API, we will end up with three ways of doing the same thing.

[yyx990803]

There is already an implementation in vue-macros that supports inferring the component types of useTemplateRef(): https://vue-macros.dev/volar/template-ref.html

Note the above usage docs is not up-to-date, to get it working:

npm i @vue-macros/volar

Then in tsconfig.json:

{
  "vueCompilerOptions": {
    "plugins": ["@vue-macros/volar/template-ref"]
  }
}

We are planning to get this into @vue/language-tools as a built-in feature with more enhancements:

1. Infer <div ref="foo"> to HTMLDivElement
2. Provide auto-completion and type errors to useTemplateRef() based on ref="xxx" presence in the current template. This can be achieved by scanning used ref="xxx" Ids in the template and then inject a string union type to useTemplateRef()'s generic args:

// user writes...
useTemplateRef()

// volar transforms it to:
// where ref="foo" and ref="bar" are present in the template
useTemplateRef<unknown, 'foo' | 'bar'>()

This means useTemplateRef() gets auto-completion for the correct ref Ids and also type error for non-existent ref Ids.

---

If I'm not misunderstanding, your proposal involves changing the way ref works right now by making it behave like a directive (like v-model). Here are my thoughts:

1. Auto-inference and strictness issues can largely be addressed even with useTemplateRef().
2. Auto-inference will still break under indirection with your proposal. Auto inference relies on both the call site and template being in the same compilation context.
3. Changing the behavior of ref is a breaking change. Changing it only when it's bound to the value of a specific function is inconsistent and can be confusing.

The only case where the current useTemplateRef() lacks, I believe, is the lack of enforced type safety when it is used in an external composable.

One thing to note is that it is already possible to enforce ref type by using function ref values:

<script setup lang="ts">
import { shallowRef } from 'vue';
const el = shallowRef<HTMLDivElement | null>()
</script>
<template>
  <img :ref="r => el = r" />
                  ^ type error
</template>

Here r defaults to Element | ComponentPublicInstance which is not very useful at the moment - but we can potentially improve this so the type of r is auto-inferred. This doesn't require changes or additions to the runtime APIs and would provide a way for composables to strictly enforce template ref types. In the meanwhile useTemplateRef() will provide a better DX for in-SFC use cases with auto-inference.

[NonSpicyBurrito]

Thank you for the response, my concern was centered around static analysis and tooling, and I'm glad to hear that it is already being considered when designing the new useTemplateRef API.
The function ref got me thinking, perhaps another potential idea could be:

<script setup lang="ts">
const foo = useTemplateRef<HTMLImgElement>()
// foo is ((el: HTMLImgElement) => void) & Ref<HTMLImgElement>
</script>

<template>
    <img :ref="foo" />
</template>

Assuming function ref will eventually get strong type safety, this could work to provide both type safety, allow template refs in composables, as well as IDE tooling like rename symbol/finding references, without needing extra changes on the language tools side or introducing breaking changes.

[yyx990803]

Challenge of this is refs are unwrapped in templates so the type of foo inside templates will just be HTMLImgElement in this case.