Template refs for DOM access in Vue

Introduction

Template refs let you get a direct link to an HTML element or component in your Vue template. This helps you interact with the element in your code, like focusing an input or measuring size.

You want to focus an input box automatically when the page loads.

You need to read or change the value of a DOM element directly.

You want to measure the size or position of an element on the screen.

You want to call a method on a child component instance.

You want to control a video or audio element directly from your code.

Syntax

Vue

<template>
  <element ref="myRef"></element>
</template>

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

const myRef = ref(null)

// Access the element with myRef.value
</script>

The ref attribute in the template names the element or component.

In the script, you create a ref variable with null initial value.

Examples

This example focuses the input box when the component loads.

Vue

<template>
  <input ref="inputBox" />
</template>

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

const inputBox = ref(null)

onMounted(() => {
  inputBox.value.focus()
})
</script>

This example logs the text inside the div after the component mounts.

Vue

<template>
  <div ref="box">Hello</div>
</template>

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

const box = ref(null)

onMounted(() => {
  console.log(box.value.textContent)
})
</script>

This example shows how to call a method on a child component using a template ref.

Vue

<template>
  <ChildComponent ref="childComp" />
</template>

<script setup>
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'

const childComp = ref(null)

function callChildMethod() {
  childComp.value.someMethod()
}
</script>

Sample Program

This component has an input box and a button. Clicking the button focuses the input box using a template ref. The input value is shown below and updates as you type.

Vue

<template>
  <input ref="nameInput" placeholder="Type your name" @input="updateValue" />
  <button @click="focusInput">Focus Input</button>
  <p>Input value: {{ inputValue }}</p>
</template>

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

const nameInput = ref(null)
const inputValue = ref('')

function focusInput() {
  nameInput.value.focus()
}

// Update inputValue when input changes
function updateValue() {
  inputValue.value = nameInput.value.value
}
</script>

<style scoped>
input {
  padding: 0.5rem;
  font-size: 1rem;
  margin-bottom: 0.5rem;
  display: block;
}
button {
  padding: 0.5rem 1rem;
  font-size: 1rem;
  cursor: pointer;
}
</style>

Important Notes

Template refs are only available after the component is mounted.

Access the DOM element with refVariable.value.

Use template refs carefully to avoid tightly coupling your code to the DOM structure.

Summary

Template refs let you directly access DOM elements or child components in Vue templates.

Use ref attribute in the template and a ref variable in the script.

They are useful for focusing inputs, reading element properties, or calling child component methods.