From c3f64b07b05a03f4046e0f635290b97f0b7bc6f9 Mon Sep 17 00:00:00 2001
From: Ali Hammoud <letsmailali.h@gmail.com>
Date: Thu, 14 Aug 2025 05:49:15 +0300
Subject: [PATCH 1/2] docs(typescript): using typescript with global custom
 directives

---
 src/guide/reusability/custom-directives.md |  4 ++
 src/guide/typescript/composition-api.md    | 44 +++++++++++++++++++++-
 src/guide/typescript/options-api.md        |  4 ++
 3 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/src/guide/reusability/custom-directives.md b/src/guide/reusability/custom-directives.md
index a8b51935f7..3325b704d0 100644
--- a/src/guide/reusability/custom-directives.md
+++ b/src/guide/reusability/custom-directives.md
@@ -110,6 +110,10 @@ app.directive('highlight', {
 })
 ```
 
+It is possible to type global custom directives by extending the `ComponentCustomProperties` interface from `vue`
+
+More Details: [Typing Custom Global Directives](/guide/typescript/composition-api#typing-global-custom-directives) <sup class="vt-badge ts" />
+
 ## When to use custom directives {#when-to-use}
 
 Custom directives should only be used when the desired functionality can only be achieved via direct DOM manipulation.
diff --git a/src/guide/typescript/composition-api.md b/src/guide/typescript/composition-api.md
index 3035afd5dc..1312438bf7 100644
--- a/src/guide/typescript/composition-api.md
+++ b/src/guide/typescript/composition-api.md
@@ -468,7 +468,8 @@ import { useTemplateRef } from 'vue'
 import MyGenericModal from './MyGenericModal.vue'
 import type { ComponentExposed } from 'vue-component-type-helpers'
 
-const modal = useTemplateRef<ComponentExposed<typeof MyGenericModal>>('modal')
+const modal =
+  useTemplateRef<ComponentExposed<typeof MyGenericModal>>('modal')
 
 const openModal = () => {
   modal.value?.open('newValue')
@@ -477,3 +478,44 @@ const openModal = () => {
 ```
 
 Note that with `@vue/language-tools` 2.1+, static template refs' types can be automatically inferred and the above is only needed in edge cases.
+
+## Typing Global Custom Directives {#typing-global-custom-directives}
+
+In order to get type hints and type checking for global custom directives declared with `app.directive()`, you can extend `ComponentCustomProperties`
+
+```ts [src/directives/highlight.ts]
+// This can be directly added to any of your `.ts` files
+// It can also be added to a `.d.ts` file. Make sure it's included in
+// project's tsconfig.json "files"
+import type { Directive } from 'vue'
+
+export type HighlightDirective = Directive<HTMLElement, string>
+
+declare module 'vue' {
+  export interface ComponentCustomProperties {
+    // prefix with v (v-highlight)
+    vHighlight: HighlightDirective
+  }
+}
+
+export default {
+  mounted: (el, binding) => {
+    el.style.backgroundColor = binding.value
+  }
+} satisfies HighlightDirective
+```
+
+```ts [main.ts]
+import highlight from './directives/highlight'
+// ...other code
+const app = createApp(App)
+app.directive('highlight', highlight)
+```
+
+Usage in component
+
+```vue [App.vue]
+<template>
+  <p v-highlight="'blue'">This sentence is important!</p>
+</template>
+```
diff --git a/src/guide/typescript/options-api.md b/src/guide/typescript/options-api.md
index 0532d3a39a..0bd343884b 100644
--- a/src/guide/typescript/options-api.md
+++ b/src/guide/typescript/options-api.md
@@ -291,3 +291,7 @@ The placement of this augmentation is subject to the [same restrictions](#type-a
 See also:
 
 - [TypeScript unit tests for component type extensions](https://github.com/vuejs/core/blob/main/packages-private/dts-test/componentTypeExtensions.test-d.tsx)
+
+## Typing Global Custom Directives {#typing-global-custom-directives}
+
+See: [Typing Custom Global Directives](/guide/typescript/composition-api#typing-global-custom-directives) <sup class="vt-badge ts" />

From 33b0dc28921c82e8c0c77327973e99c48509d56a Mon Sep 17 00:00:00 2001
From: Ali Hammoud <letsmailali.h@gmail.com>
Date: Thu, 14 Aug 2025 05:53:14 +0300
Subject: [PATCH 2/2] remove description

---
 src/guide/typescript/composition-api.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/src/guide/typescript/composition-api.md b/src/guide/typescript/composition-api.md
index 1312438bf7..4a7376803b 100644
--- a/src/guide/typescript/composition-api.md
+++ b/src/guide/typescript/composition-api.md
@@ -484,9 +484,6 @@ Note that with `@vue/language-tools` 2.1+, static template refs' types can be au
 In order to get type hints and type checking for global custom directives declared with `app.directive()`, you can extend `ComponentCustomProperties`
 
 ```ts [src/directives/highlight.ts]
-// This can be directly added to any of your `.ts` files
-// It can also be added to a `.d.ts` file. Make sure it's included in
-// project's tsconfig.json "files"
 import type { Directive } from 'vue'
 
 export type HighlightDirective = Directive<HTMLElement, string>