useVueTemplateRef (JavaScript)

Language JavaScript (and super languages)

Summary

Rule available since: v2.6.4
Diagnostic Category: lint/nursery/useVueTemplateRef
This rule doesn’t have a fix.
The default severity of this rule is information.
This rule belongs to the following domains:
- vue
Sources:
- Inspired from vue/prefer-use-template-ref

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useVueTemplateRef": "error"
6
      }
7
    }
8
  }
9
}

Description

Require useTemplateRef() instead of ref() or shallowRef() to access elements of the template.

A template ref gives your script access to an element or a child component of the template. You name the element with the ref attribute, as in <input ref="input" />.

In <script setup>, Vue fills in a variable created with ref() or shallowRef() when the variable has the same name as a ref attribute. The link between the two is only the name, so renaming the variable silently breaks it. The variable also looks like any other piece of state, which makes it hard to tell that the template fills it in.

Vue 3.5 added useTemplateRef(), which takes the name of the ref attribute as an argument. The variable can then have any name, and the call shows that the value comes from the template.

This rule reports a variable declared at the top level of <script setup> with ref() or shallowRef() when an element of the template has a ref attribute with the same name.

A ref attribute with a dynamic value, such as :ref="(el) => (input = el)", isn’t reported, because the function decides where the element is stored.

Examples

Invalid

1
<template>
2
  <input ref="input" />
3
</template>
4

5
<script setup>
6
import { ref } from "vue";
7

8
const input = ref();
9
</script>

1
<template>
2
  <div ref="root" />
3
</template>
4

5
<script setup>
6
import { shallowRef } from "vue";
7

8
const root = shallowRef(null);
9
</script>

Valid

1
<template>
2
  <input ref="input" />
3
  <button :ref="(el) => (button = el)">Send</button>
4
</template>
5

6
<script setup>
7
import { ref, useTemplateRef } from "vue";
8

9
const inputElement = useTemplateRef("input");
10
const button = ref();
11
</script>