first

.cursor/skills/vue/references/features-template-refs.md

@@ -0,0 +1,212 @@
+---
+name: template-refs
+description: 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:
+
+```vue
+<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:
+
+```vue
+<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:
+
+```vue
+<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:
+
+```vue
+<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:
+
+```vue
+<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`:
+
+```vue
+<!-- 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
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from 'vue'
+
+const inputRef = useTemplateRef<HTMLInputElement>('input')
+
+function focusInput() {
+  inputRef.value?.focus()
+}
+</script>
+```
+
+### Scroll Control
+
+```vue
+<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
+
+```vue
+<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
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/essentials/template-refs.html
+- https://vuejs.org/guide/typescript/composition-api.html#typing-template-refs
+-->