new function for template refs in setup functions

[theoephraim]

Just a small suggestion to introduce a new function for template refs in order to increase readability in setup functions.

For example, currently to reference a component in our template (for example <Popup ref="popup" ... />) we would write

const popup = ref(null); // does something very special because ref="popup" exists in the template ✨
const loggedOutAt = ref(null); // looks identical but does something totally different 😢

The ref name in the template must match our variable name exactly, and it is not immediately obvious that this ref does anything special compared to any other reactive ref which could be holding any other data.

Perhaps there are some important under the hood reasons for marrying the general reactivity ref with template refs, but I think it is slightly confusing and could be made more clear.

What does the proposed API look like?

I suggest we just add a new function to distinguish regular refs from template refs and removes the tight coupling of the variable name. For example:

import { templateRef } from 'vue';

const myPopup = templateRef('popup');

This will be immediately obvious to readers that myPopup is referencing something from the template, and it frees the user up to name the variable as they like. It also means we can make some type assumptions about whats there and what type can be set by the user. Perhaps this could even fire off a warning / error if the ref was not found (toggle-able for when this might be expected).

The function could be called templateRef, getTemplateRef, useTemplateRef, defineTemplateRef, etc... Depends on what the current conventions are with "use" and "define" and if this fits well enough into either...

I think ideally we would deprecate the current behaviour (eventually) to reduce confusion and API surface area.

Thoughts?

(As always thanks for all your hard work on driving vue forward! <3)

[theoephraim]

This seems like a fairly straightforward win without any drawbacks - other than a slightly increased api surface (which ideally would be eventually phased out).

Would love some feedback from the core team and if there is interest I could drive this forward into an actual PR.

What is the best way to get that feedback? Discord? Tagging people? (@yyx990803 @LinusBorg ?)

Thanks!!

[jods4]

Before committing to templateRef(), I would love to discuss alternatives. Some ideas:

1. Could we optionally bind DOM ref to plain variables/state instead of reactive refs?
   The vast majority of the time, my DOM refs aren't dynamic and I just know they will be set when mounted and never change.
   In these cases having to store them in reactive ref and accessing with .value is just bloat.
   At least in the new Vue 3 Composition API this should be possible (last time I asked I think some concerns were raised regarding the Options API and/or back-compat with Vue 2).

2. Maybe a defineDomRefs() that returns one (reactive) object with all the DOM refs -- aka $refs in template -- would be more convenient to use than having to declare several refs individually and accessing with .value. TS typing might be an issue, though.

[hubdidub]

In vuejs/core@3ba70e4 they added a function called useTemplateRef to the minor branch for 3.5 (currently in alpha stage). I'm very happy about that, I think this is a very nice addition! :)

Well maybe it is too late now, or maybe it's a good opportunity since it's not fully released yet. But I'd like to add an idea that involves using useTemplateRef with child components and Typescript:

<script setup lang="ts">
import { ref, useTemplateRef } from 'vue';
import MyComp from './MyComp.vue';

// Old way
const myCompRef = ref<InstanceType<typeof MyComp>>();

// New way
const foo = useTemplateRef<InstanceType<typeof MyComp>>('myCompRef');

</script>

<template>
  <my-comp ref="myCompRef" />
</template>

Could we somehow get rid of the InstanceType helper with this? Maybe even the typeof too?
I'm thinking, maybe the useTemplateRef function could detect if we are dealing with a Vue component and then auto-wrap it in an InstanceType for us?

Not sure if it's possible. But if it is, I think that would make the code even more readable:

const foo = useTemplateRef<typeof MyComp>('myCompRef');

[theoephraim]

@hubdidub - woohoo! thanks for the heads up!

Definitely the extra typing is a bit awkward and anything else we can do to make it more automatic would be awesome. Probably a much bigger chunk of work though (if it's possible). Looks like @yyx990803 wrote the commit, so he'd probably know.

I'd also suggest the addition of a feature to throw an error if the ref was not found (w/ ability to disable it if this might be expected).

[hubdidub]

We can already get the error when we access something from the ref:

myTemplateRef.value?.someFunction(); // will not error when the element isn't mounted
myTemplateRef.value!.someFunction(); // will error when the element isn't mounted
// (or when not using ts, without the !)

But a specific error message or warning from inside useTemplateRef could be helpful too.

[theoephraim]

Yeah the common case I have encountered is that you do expect it to be there, so adding the extra ?/! and additional error checking feels a bit repetitive. If useTemplateRef expected the thing to definitely be there, then it could already throw if it's missing (no additional check necessary and with a nicer error message) and then the type would not need to be possibly undefined.

[KazariEX]

Is it possible to automatically infer the type of template refs?

[hubdidub]

@KazariEX Evan talked about it a bit in that discussion over at the core repo: vuejs/core#11408 (comment)

[zhangenming]

how about
const {popup:myPopup }= useTemplateRef();

[KazariEX]

It should be named useTemplateRefs