gt-agent-company/.agents/skills/vue/references/features-template-refs.md

name, description

name	description
template-refs	Access DOM elements and child component instances directly

Template Refs

Template refs provide direct access to DOM elements and child component instances.

Basic Usage (3.5+)

Use useTemplateRef() for type-safe refs:

<script setup lang="ts">
import { useTemplateRef, onMounted } from 'vue'

const inputRef = useTemplateRef<HTMLInputElement>('input')

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

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

Legacy Approach (Pre-3.5)

Use a ref with matching name:

<script setup lang="ts">
import { ref, onMounted } from 'vue'

const inputRef = ref<HTMLInputElement | null>(null)

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

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

Refs in v-for

Collect multiple refs into an array:

<script setup lang="ts">
import { ref, onMounted } from 'vue'

const items = ref([1, 2, 3])
const itemRefs = ref<HTMLLIElement[]>([])
</script>

<template>
  <ul>
    <li v-for="item in items" ref="itemRefs">
      {{ item }}
    </li>
  </ul>
</template>

Note: ref array order is not guaranteed to match source array order.

Function Refs

Use a function for full control:

<script setup lang="ts">
const elements = new Map<number, HTMLElement>()

function setItemRef(el: HTMLElement | null, id: number) {
  if (el) {
    elements.set(id, el)
  } else {
    elements.delete(id)
  }
}
</script>

<template>
  <div v-for="item in items" :ref="(el) => setItemRef(el, item.id)">
    {{ item.name }}
  </div>
</template>

Component Refs

Access child component instance:

<script setup lang="ts">
import { useTemplateRef, onMounted } from 'vue'
import Child from './Child.vue'

type ChildInstance = InstanceType<typeof Child>
const childRef = useTemplateRef<ChildInstance>('child')

onMounted(() => {
  // Access exposed properties/methods
  childRef.value?.someMethod()
})
</script>

<template>
  <Child ref="child" />
</template>

Exposing Component Properties

By default, <script setup> components are closed. Use defineExpose:

<!-- Child.vue -->
<script setup lang="ts">
import { ref } from 'vue'

const count = ref(0)
const increment = () => count.value++

// Only these are accessible via ref
defineExpose({
  count,
  increment
})
</script>

Common Use Cases

Focus Management

<script setup lang="ts">
import { useTemplateRef } from 'vue'

const inputRef = useTemplateRef<HTMLInputElement>('input')

function focusInput() {
  inputRef.value?.focus()
}
</script>

Scroll Control

<script setup lang="ts">
import { useTemplateRef } from 'vue'

const containerRef = useTemplateRef<HTMLDivElement>('container')

function scrollToBottom() {
  const el = containerRef.value
  if (el) {
    el.scrollTop = el.scrollHeight
  }
}
</script>

Third-Party Library Integration

<script setup lang="ts">
import { useTemplateRef, onMounted, onUnmounted } from 'vue'
import Chart from 'chart.js'

const canvasRef = useTemplateRef<HTMLCanvasElement>('canvas')
let chart: Chart | null = null

onMounted(() => {
  if (canvasRef.value) {
    chart = new Chart(canvasRef.value, {
      // options
    })
  }
})

onUnmounted(() => {
  chart?.destroy()
})
</script>

<template>
  <canvas ref="canvas"></canvas>
</template>

Important Notes

1. Refs are null before mount - access in onMounted or later
2. Conditional refs can be null - elements with v-if may not exist
3. Use optional chaining - ref.value?.method() for safety
4. Avoid overusing - prefer declarative approaches when possible