Template refs (Options API)

src/.vuepress/config.js

@@ -27,6 +27,7 @@ const sidebar = {
         '/guide/component-slots',
         '/guide/component-provide-inject',
         '/guide/component-dynamic-async',
+        '/guide/component-template-refs',
         '/guide/component-edge-cases'
       ]
     },

src/api/composition-api.md

@@ -291,7 +291,7 @@ const foo = inject<string>('foo') // string | undefined
 
 ## Template Refs
 
-When using the Composition API, the concept of [reactive refs](./refs-api.html#ref) and [template refs](TODO) are unified. In order to obtain a reference to an in-template element or component instance, we can declare a ref as usual and return it from `setup()`:
+When using the Composition API, the concept of [reactive refs](./refs-api.html#ref) and [template refs](../guide/component-template-refs.html) are unified. In order to obtain a reference to an in-template element or component instance, we can declare a ref as usual and return it from `setup()`:
 
 ```html
 <template>

src/api/instance-properties.md

@@ -126,10 +126,10 @@
 
 - **Details:**
 
-An object of DOM elements and component instances, registered with [`ref` attributes](TODO).
+An object of DOM elements and component instances, registered with [`ref` attributes](../guide/component-template-refs.html).
 
 - **See also:**
-  - [Child Component Refs](TODO:refs)
+  - [Template refs](../guide/component-template-refs.html)
   - [Special Attributes - ref](./special-attributes.md#ref)
 
 ## $attrs

src/api/special-attributes.md

@@ -49,7 +49,7 @@
 
   An important note about the ref registration timing: because the refs themselves are created as a result of the render function, you cannot access them on the initial render - they don't exist yet! `$refs` is also non-reactive, therefore you should not attempt to use it in templates for data-binding.
 
-- **See also:** [Child Component Refs](TODO-handling-edge-cases)
+- **See also:** [Child Component Refs](../guide/component-template-refs.html)
 
 ## is
 

src/guide/component-template-refs.md

@@ -0,0 +1,47 @@
+# Template refs
+
+> This page assumes you've already read the [Components Basics](component-basics.md). Read that first if you are new to components.
+
+Despite the existence of props and events, sometimes you might still need to directly access a child component in JavaScript. To achieve this you can assign a reference ID to the child component or HTML element using the `ref` attribute. For example:
+
+```html
+<input ref="input" />
+```
+
+This may be useful when you want to, for example, programmatically focus this input on component mount:
+
+```js
+const app = Vue.createApp({})
+
+app.component('base-input', {
+  template: `
+    <input ref="input" />
+  `,
+  methods: {
+    focusInput() {
+      this.$refs.input.focus()
+    }
+  },
+  mounted() {
+    this.focusInput()
+  }
+})
+```
+
+Also, you can add another `ref` to the component itself and use it to trigger `focusInput` event from the parent component:
+
+```html
+<base-input ref="usernameInput"></base-input>
+```
+
+```js
+this.$refs.usernameInput.focusInput()
+```
+
+When `ref` is used together with `v-for`, the ref you get will be an array containing the child components mirroring the data source.
+
+::: warning
+`$refs` are only populated after the component has been rendered. It is only meant as an escape hatch for direct child manipulation - you should avoid accessing `$refs` from within templates or computed properties.
+:::
+
+**See also**: [Using template refs in Composition API](../api/composition-api.html#template-refs)