Vue · all subjects

template-refs

22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

template ref definition

A template ref refers to using a ref attribute on a tag within a template. After the component renders, this attribute is used to populate a corresponding property with either the HTML element or the component instance that corresponds to the tag in the template.

template ref in Options API

If you are using the Options API then the refs are exposed via properties of the $refs object.

template ref in Composition API

With the Composition API, template refs populate a reactive ref with the same name.

template ref vs reactive ref

Template refs should not be confused with the reactive refs found in Vue's reactivity system.

useTemplateRef() helper in Vue 3.5+

In Vue 3.5+, use the useTemplateRef() helper from the Composition API to obtain template refs. The first argument must match the ref value in the template. Example: const input = useTemplateRef('my-input') obtains the reference in a component with ref="my-input" in the template.

ref attribute for direct DOM access

The ref attribute allows obtaining a direct reference to a specific DOM element or child component instance after it is mounted. It is used like <input ref="input">.

TypeScript type inference with template refs

When using TypeScript, Vue's IDE support and vue-tsc automatically infer the type of input.value based on what element or component the matching ref attribute is used on.

Template refs before Vue 3.5

Before Vue 3.5, declare a ref with a name matching the template ref attribute's value: const input = ref(null) with ref="input" in the template. When not using <script setup>, return the ref from setup().

Accessing refs with Options API

In the Options API, refs are exposed on this.$refs. Access them in the mounted() lifecycle hook: this.$refs.input.focus().

Template refs are null/undefined before mount

Template refs can only be accessed after the component is mounted. If you try to access a ref in a template expression on the first render, it will be null (Composition API) or undefined (Options API) because the element does not exist until after the first render.

Watching template refs must handle null values

When watching template ref changes in the Composition API, account for the case where the ref has a null value using watchEffect with a conditional check.

Template refs on child components

The ref attribute can also be used on a child component. The reference will be that of the component instance: <Child ref="child" />.

Component refs give full access to component instance

When a parent component references a child component via template refs, the referenced instance will be identical to the child component's this, giving full access to every property and method. This creates tight coupling, so component refs should only be used when absolutely needed; props and emit interfaces should be preferred.

defineExpose() for <script setup> component refs

Components using <script setup> are private by default. To expose a public interface to parent components referencing them via template refs, use the defineExpose() macro: defineExpose({ a, b }). Refs are automatically unwrapped like on normal instances.

defineExpose() must be called before await

defineExpose() must be called before any await operation. Properties and methods exposed after the await operation will not be accessible.

expose option in Options API

In the Options API, the expose option can be used to limit access to a child instance. It accepts an array of property and method names: expose: ['publicData', 'publicMethod']. Only those listed will be accessible to parents via template refs.

Refs inside v-for collect into array

When ref is used inside v-for (requires v3.5+), the corresponding ref should contain an array value, which will be populated with the elements after mount. With useTemplateRef(), use: const itemRefs = useTemplateRef('items') paired with ref="items" on the loop element.

Template ref arrays do not guarantee source array order

When using refs inside v-for, the ref array does not guarantee the same order as the source array.

Function refs for custom storage

Instead of a string key, the ref attribute can be bound to a function using a dynamic :ref binding. The function is called on each component update and receives the element reference as the first argument. When the element is unmounted, the argument will be null. Example: :ref="(el) => { /* assign el to a property or ref */ }".

Template refs are similar to v-for key attribute

The ref attribute is special, similar to the key attribute discussed in the v-for chapter.

useTemplateRef() creates shallow ref synced with template element

useTemplateRef() returns a shallow ref whose value will be synced with the template element or component with a matching ref attribute. Available in 3.5+. Type signature: function useTemplateRef<T>(key: string): Readonly<ShallowRef<T | null>>

useTemplateRef() example with input focus

Example using useTemplateRef() to get a reference to an input element and call focus() on it: import { useTemplateRef, onMounted } from 'vue'; const inputRef = useTemplateRef('input'); onMounted(() => { inputRef.value.focus() }); <template><input ref="input" /></template>

Give your agent this brain