Vue 3 has a declarative rendering model. Basically, this model abstracts away most of the direct DOM access. However, sometimes, we may need to access the underlying DOM element directly. In this case, we can use the Vue 3 Template Refs.

In case you are new to VueJS, you can start with a basic primer Vue 3 Options API vs Composition API.

1 – Why Vue 3 Template Refs?

VueJS provides a special attribute known as ref. This attribute allows us to obtain a direct reference to a DOM element or even a child component instance after it is mounted.

Vue 3 Template Refs are extremely useful in case when we want to programmatically focus an input on component mount or initialize a 3rd party library on an element.

2 – Vue 3 Template Refs Example

To obtain a reference with Composition API, we need to declare a ref with the same name.

See below example:

<script setup>
import { ref, onMounted } from 'vue'

const saySomething = ref(null)

onMounted(() => {

  <input ref="saySomething" />

As you can see, we declare a ref named saySomething. We specify the same name in the ref attribute of the input element.

Once the component is mounted, we can access the ref element and do something with it. In this case, we focus on the element.

Note that we can only access the ref after the component is mounted.

3 – Vue 3 ref with Watchers

When we are trying to use the Vue 3 ref with a watcher, we need to make sure that it does not contain a null value.

See below example:

watchEffect(() => {
  if (saySomething.value) {
  } else {

Basically, in the else part, we need to handle the case when saySomething was null.

If interested, you can read more about watchers in this detailed post on Vue3 Watchers with Composition API.

4 – Template Refs with v-for

We can also use Vue 3 Refs within v-for blocks. However, the corresponding ref variable should contain an array value.

See below example:

<script setup>
import { ref, onMounted } from 'vue'

const list = ref([
  /* some list */

const itemRefs = ref([])

onMounted(() => console.log(itemRefs.value))

    <li v-for="item in list" ref="itemRefs">
      {{ item }}

As you can see here, the itemRefs expects an array.

You can read more about rendering lists in VueJS in this detailed post on VueJS v-for directive.

Do note that the ref array does not guarantee the same order as the source array.


Vue 3 Template Refs are an important tool in your VueJS toolkit. When we want to direct access to the DOM elements, ref is the best option to use.

Want to handle form fields in VueJS? Check out our detailed post on Vue 3 form handling.

If you have any comments or queries about this post, please feel free to mention them in the comments section below.

Categories: VueJS


Leave a Reply

Avatar placeholder

Your email address will not be published. Required fields are marked *