From 66e21e378611dd4d4a458e4c543c7ddcd068f525 Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Tue, 15 Jul 2025 11:02:06 +0100
Subject: [PATCH] feat: drop templateRef

Removes templateRef now that vue itself has `useTemplateRef` built in.
---
 packages/core/index.ts                  |   1 -
 packages/core/templateRef/index.md      |  60 --------------
 packages/core/templateRef/index.test.ts | 103 ------------------------
 packages/core/templateRef/index.ts      |  34 --------
 test/exports/core.yaml                  |   1 -
 5 files changed, 199 deletions(-)
 delete mode 100644 packages/core/templateRef/index.md
 delete mode 100644 packages/core/templateRef/index.test.ts
 delete mode 100644 packages/core/templateRef/index.ts

diff --git a/packages/core/index.ts b/packages/core/index.ts
index 7a98fe414a1..75183314dea 100644
--- a/packages/core/index.ts
+++ b/packages/core/index.ts
@@ -8,7 +8,6 @@ export * from './onElementRemoval'
 export * from './onKeyStroke'
 export * from './onLongPress'
 export * from './onStartTyping'
-export * from './templateRef'
 export * from './unrefElement'
 export * from './useActiveElement'
 export * from './useAnimate'
diff --git a/packages/core/templateRef/index.md b/packages/core/templateRef/index.md
deleted file mode 100644
index 8e95da8c5cc..00000000000
--- a/packages/core/templateRef/index.md
+++ /dev/null
@@ -1,60 +0,0 @@
----
-category: Component
----
-
-# templateRef
-
-Shorthand for binding ref to template element.
-
-## Usage
-
-<!-- eslint-skip -->
-
-```vue
-<script lang="ts">
-import { templateRef } from '@vueuse/core'
-
-export default {
-  setup() {
-    const target = templateRef('target')
-
-    // no need to return the `target`, it will bind to the ref magically
-  },
-}
-</script>
-
-<template>
-  <div ref="target" />
-</template>
-```
-
-### With JSX/TSX
-
-```tsx
-import { templateRef } from '@vueuse/core'
-
-export default {
-  setup() {
-    const target = templateRef<HTMLElement | null>('target', null)
-
-    // use string ref
-    return () => <div ref="target"></div>
-  },
-}
-```
-
-### `<script setup>`
-
-There is no need for this when using with `<script setup>` since all the variables will be exposed to the template. It will be exactly the same as `ref`.
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-
-const target = ref<HTMLElement | null>(null)
-</script>
-
-<template>
-  <div ref="target" />
-</template>
-```
diff --git a/packages/core/templateRef/index.test.ts b/packages/core/templateRef/index.test.ts
deleted file mode 100644
index 09fbd8eb4c0..00000000000
--- a/packages/core/templateRef/index.test.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { defineComponent, h, nextTick, shallowRef } from 'vue'
-import { mount } from '../../.test'
-import { templateRef } from './index'
-
-describe('templateRef', () => {
-  it('should be defined', () => {
-    expect(templateRef).toBeDefined()
-  })
-
-  it('string ref mount', () => {
-    const refKey = 'target'
-
-    const vm = mount(defineComponent({
-      setup() {
-        const targetEl = templateRef<HTMLElement | null>(refKey, null)
-        return { targetEl }
-      },
-      render() {
-        return h('div', { ref: refKey })
-      },
-    }))
-
-    expect(vm.targetEl).toBe(vm.$el)
-  })
-
-  it('string ref update', async () => {
-    const vm = mount(defineComponent({
-      setup() {
-        const refKey = shallowRef('foo')
-        const fooEl = templateRef<HTMLElement | null>('foo', null)
-        const barEl = templateRef<HTMLElement | null>('bar', null)
-        return {
-          refKey,
-          fooEl,
-          barEl,
-        }
-      },
-      render() {
-        return h('div', { ref: this.refKey })
-      },
-    }))
-
-    expect(vm.fooEl).toBe(vm.$el)
-    expect(vm.barEl).toBe(null)
-
-    vm.refKey = 'bar'
-    await nextTick()
-
-    expect(vm.fooEl).toBe(null)
-    expect(vm.barEl).toBe(vm.$el)
-  })
-
-  it('string ref unmount', async () => {
-    const vm = mount(defineComponent({
-      setup() {
-        const toggle = shallowRef(true)
-        const targetEl = templateRef<HTMLElement | null>('target', null)
-        return {
-          toggle,
-          targetEl,
-        }
-      },
-      render() {
-        return this.toggle ? h('div', { ref: 'target' }) : null
-      },
-    }))
-
-    expect(vm.targetEl).toBe(vm.$el)
-
-    vm.toggle = false
-    await nextTick()
-
-    expect(vm.targetEl).toBe(null)
-  })
-
-  it('support vue component as ref', async () => {
-    const ChildComponent = defineComponent({
-      name: 'ChildComponent',
-      render() {
-        return null
-      },
-    })
-
-    const vm = mount(defineComponent({
-      components: {
-        ChildComponent,
-      },
-      setup() {
-        const targetEl = templateRef<typeof ChildComponent>('target')
-        return {
-          targetEl,
-        }
-      },
-      render() {
-        return h(ChildComponent, { ref: 'target' })
-      },
-    }))
-
-    expect(vm.targetEl).toBeDefined()
-    expect(vm.targetEl.$options.name).toBe('ChildComponent')
-  })
-})
diff --git a/packages/core/templateRef/index.ts b/packages/core/templateRef/index.ts
deleted file mode 100644
index c673136bb34..00000000000
--- a/packages/core/templateRef/index.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import type { Component, Ref } from 'vue'
-import { tryOnMounted } from '@vueuse/shared'
-import { customRef, getCurrentInstance, onUpdated } from 'vue'
-
-/**
- * Shorthand for binding ref to template element.
- *
- * @see https://vueuse.org/templateRef
- * @param key
- * @param initialValue
- */
-export function templateRef<T extends HTMLElement | SVGElement | Component | null, Keys extends string = string>(
-  key: Keys,
-  initialValue: T | null = null,
-): Readonly<Ref<T>> {
-  const instance = getCurrentInstance()
-  let _trigger = () => {}
-
-  const element = customRef((track, trigger) => {
-    _trigger = trigger
-    return {
-      get() {
-        track()
-        return instance?.proxy?.$refs[key] ?? initialValue
-      },
-      set() {},
-    }
-  })
-
-  tryOnMounted(_trigger)
-  onUpdated(_trigger)
-
-  return element as Readonly<Ref<T>>
-}
diff --git a/test/exports/core.yaml b/test/exports/core.yaml
index 940cf741d90..084755312e5 100644
--- a/test/exports/core.yaml
+++ b/test/exports/core.yaml
@@ -107,7 +107,6 @@
   StorageSerializers: object
   syncRef: function
   syncRefs: function
-  templateRef: function
   throttledRef: function
   throttledWatch: function
   throttleFilter: function