From 69a7b957d5ecc0b26d63112ebb20765a85874993 Mon Sep 17 00:00:00 2001
From: Benjamin Canac <canacb1@gmail.com>
Date: Mon, 30 Jun 2025 15:01:58 +0200
Subject: [PATCH] feat(Tooltip): add `reference` prop

Resolves #4430
---
 .../examples/tooltip/TooltipCursorExample.vue | 41 +++++++++++++++++++
 docs/content/3.components/tooltip.md          | 14 +++++++
 src/runtime/components/Tooltip.vue            |  5 ++-
 3 files changed, 58 insertions(+), 2 deletions(-)
 create mode 100644 docs/app/components/content/examples/tooltip/TooltipCursorExample.vue

diff --git a/docs/app/components/content/examples/tooltip/TooltipCursorExample.vue b/docs/app/components/content/examples/tooltip/TooltipCursorExample.vue
new file mode 100644
index 00000000..2424b4ad
--- /dev/null
+++ b/docs/app/components/content/examples/tooltip/TooltipCursorExample.vue
@@ -0,0 +1,41 @@
+<script setup lang="ts">
+const open = ref(false)
+const anchor = ref({ x: 0, y: 0 })
+
+const reference = computed(() => ({
+  getBoundingClientRect: () =>
+    ({
+      width: 0,
+      height: 0,
+      left: anchor.value.x,
+      right: anchor.value.x,
+      top: anchor.value.y,
+      bottom: anchor.value.y,
+      ...anchor.value
+    } as DOMRect)
+}))
+</script>
+
+<template>
+  <UTooltip
+    :open="open"
+    :reference="reference"
+    :content="{ side: 'top', sideOffset: 16, updatePositionStrategy: 'always' }"
+  >
+    <div
+      class="flex items-center justify-center rounded-md border border-dashed border-accented text-sm aspect-video w-72"
+      @pointerenter="open = true"
+      @pointerleave="open = false"
+      @pointermove="(ev) => {
+        anchor.x = ev.clientX
+        anchor.y = ev.clientY
+      }"
+    >
+      Hover me
+    </div>
+
+    <template #content>
+      {{ anchor.x.toFixed(0) }} - {{ anchor.y.toFixed(0) }}
+    </template>
+  </UTooltip>
+</template>
diff --git a/docs/content/3.components/tooltip.md b/docs/content/3.components/tooltip.md
index 9381cca5..1b46ffb3 100644
--- a/docs/content/3.components/tooltip.md
+++ b/docs/content/3.components/tooltip.md
@@ -186,6 +186,20 @@ name: 'tooltip-open-example'
 In this example, leveraging [`defineShortcuts`](/composables/define-shortcuts), you can toggle the Tooltip by pressing :kbd{value="O"}.
 ::
 
+### With following cursor :badge{label="Soon" class="align-text-top"}
+
+You can make the Tooltip follow the cursor when hovering over an element using the [`reference`](https://reka-ui.com/docs/components/tooltip#trigger) prop:
+
+::component-example
+---
+name: 'tooltip-cursor-example'
+---
+::
+
+::note
+This example is based on Reka UI's [Tooltip Cursor](https://reka-ui.com/examples/tooltip-cursor) example.
+::
+
 ## API
 
 ### Props
diff --git a/src/runtime/components/Tooltip.vue b/src/runtime/components/Tooltip.vue
index f554824e..1595681b 100644
--- a/src/runtime/components/Tooltip.vue
+++ b/src/runtime/components/Tooltip.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { TooltipRootProps, TooltipRootEmits, TooltipContentProps, TooltipContentEmits, TooltipArrowProps } from 'reka-ui'
+import type { TooltipRootProps, TooltipRootEmits, TooltipContentProps, TooltipContentEmits, TooltipArrowProps, TooltipTriggerProps } from 'reka-ui'
 import type { AppConfig } from '@nuxt/schema'
 import theme from '#build/ui/tooltip'
 import type { KbdProps } from '../types'
@@ -27,6 +27,7 @@ export interface TooltipProps extends TooltipRootProps {
    * @defaultValue true
    */
   portal?: boolean | string | HTMLElement
+  reference?: TooltipTriggerProps['reference']
   class?: any
   ui?: Tooltip['slots']
 }
@@ -70,7 +71,7 @@ const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.tooltip || {
 
 <template>
   <TooltipRoot v-slot="{ open }" v-bind="rootProps">
-    <TooltipTrigger v-if="!!slots.default" v-bind="$attrs" as-child :class="props.class">
+    <TooltipTrigger v-if="!!slots.default || !!reference" v-bind="$attrs" as-child :reference="reference" :class="props.class">
       <slot :open="open" />
     </TooltipTrigger>