[ Vue3 Built-in Attributes](#)
* * *
The `ref` attribute is used to register reference information for elements or child components, allowing direct access to DOM elements or component instances in JavaScript code.
* * *
## Basic Description
`ref` is an important way to obtain DOM elements or component instances in Vue. It allows us to manipulate the DOM or call child component methods after the Vue instance is mounted.
* **Type**: String | Function
* **Purpose**: Access DOM elements or child component instances for focus control, method calls, and other operations.
* * *
## Basic Usage
### 1. Using ref in Options API
In Options API, references registered with ref are stored in the component instance's `$refs` object:
## Example
export default {
methods: {
focusInput() {
// Access DOM element through $refs
this.$refs.inputField.focus()
}
}
}
### 2. Using ref in Composition API
In Composition API, it is recommended to use `useTemplateRef` to obtain template references:
## Example
import { useTemplateRef } from 'vue'
// Create a reference matching the ref name in the template
const inputField = useTemplateRef('inputField')
function focusInput() {
// Directly access DOM element
inputField.value?.focus()
}
* * *
## Usage Scenarios
### 1. Accessing DOM Elements
Using ref allows direct access to DOM elements for focus control, value retrieval, and other operations:
## Example
export default {
methods: {
getValue() {
// Get input value
const value = this.$refs.username.value
console.log('Input value:', value)
}
}
}
### 2. Accessing Child Component Instances
Using ref allows access to child component instances, calling child component methods or accessing their data:
## Example
import ChildComponent from './ChildComponent.vue'
export default {
components: {
ChildComponent
},
methods: {
callChildMethod() {
// Call child component method
this.$refs.childRef.sayHello()
// Access child component data
console.log('Child component data:', this.$refs.childRef.message)
}
}
}
### 3. Function-based ref
ref can also accept a function, which will be called on each update, allowing full control over where the reference is stored:
## Example
inputEl = el" />
export default {
data() {
return {
inputEl: null
}
},
methods: {
focusInput() {
this.inputEl?.focus()
}
}
}
* * *
## Notes
> **ref Registration Timing**: Since refs are created by the rendering function's result, they can only be accessed after the component is mounted. If accessed in the `created` lifecycle hook, `$refs` will still be an empty object.
> **Non-reactive**: `$refs` is non-reactive, so it should not be used for data binding in templates. Only use it for DOM operations in JavaScript.
> **Avoid Overusing ref**: Whenever possible, manipulate DOM and child components through data-driven approaches and event handling. Excessive use of ref makes code difficult to maintain.
## Example
export default {
created() {
console.log(this.$refs.inputField) // undefined
},
mounted() {
console.log(this.$refs.inputField) // accessible
}
}
* * *
## Working with v-for
ref can also be used with `v-for`, creating an array containing all corresponding DOM elements or component instances:
## Example
YouTip