{"id":12453,"library":"vue-debounce","title":"Vue Debounce Directive","description":"vue-debounce is a Vue.js directive that provides a straightforward way to debounce events, primarily user input, within Vue 3 applications. As of its current stable version, 5.0.1, it exclusively supports Vue 3; users requiring Vue 2 compatibility are directed to the separate `vue2-debounce` package or to remain on v4 of vue-debounce. The library is actively maintained, with a cadence of minor and patch releases, and major versions introducing significant architectural shifts such as the transition to ES modules. Its key differentiators include a simple declarative usage model via the `v-debounce` directive, support for various event listeners, customizable debounce times, and several modifiers like `lock`, `fireonempty`, and `trim` for fine-grained control over debouncing behavior. It supports both global application-level registration and component-level usage.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/dhershman1/vue-debounce","tags":["javascript","vue","vue3","debounce","directive","simple","v-debounce","events","typescript"],"install":[{"cmd":"npm install vue-debounce","lang":"bash","label":"npm"},{"cmd":"yarn add vue-debounce","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-debounce","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency for Vue.js applications.","package":"vue","optional":false}],"imports":[{"note":"Since v5.0.0, vue-debounce is an ES module. CommonJS `require` syntax will fail or lead to incorrect imports. Use the default import for global registration.","wrong":"const vueDebounce = require('vue-debounce')","symbol":"vueDebounce","correct":"import vueDebounce from 'vue-debounce'"},{"note":"Import for TypeScript type definitions to configure global debounce options.","symbol":"DebounceOptions","correct":"import type { DebounceOptions } from 'vue-debounce'"},{"note":"For Vue 2 applications, use the dedicated `vue2-debounce` package. `vue-debounce` v5+ is Vue 3 only.","wrong":"import vueDebounce from 'vue-debounce'","symbol":"Vue 2 support","correct":"import vueDebounce from 'vue2-debounce'"}],"quickstart":{"code":"import vueDebounce from 'vue-debounce';\nimport { createApp } from 'vue';\nimport App from './App.vue';\n\nconst app = createApp(App);\n\n// Register the directive globally with custom options\napp\n  .directive('debounce', vueDebounce({\n    lock: false, // Lock all debounced inputs by default\n    defaultTime: '500ms', // Default debounce time for directives without a specified time\n    listenTo: ['keyup', 'change'] // Listen to multiple events\n  }))\n  .mount('#app');\n\n// In your App.vue template:\n// <template>\n//   <div>\n//     <input v-debounce:800ms.trim=\"mySearchFunction\" placeholder=\"Search...\" />\n//     <button v-debounce=\"myClickHandler\">Click Me</button>\n//   </div>\n// </template>\n\n// In your component script:\n// export default {\n//   methods: {\n//     mySearchFunction(value) {\n//       console.log('Debounced search for:', value);\n//     },\n//     myClickHandler() {\n//       console.log('Debounced click!');\n//     }\n//   }\n// }","lang":"typescript","description":"This quickstart demonstrates how to globally register the `v-debounce` directive in a Vue 3 application, including custom default options. It also shows basic template usage with a specified debounce time and modifiers."},"warnings":[{"fix":"For Vue 2 projects, install `vue2-debounce` (npm i vue2-debounce) or downgrade `vue-debounce` to v4 (npm i vue-debounce@4).","message":"Vue Debounce v5.0.0 completely removes support for Vue 2. If your project relies on Vue 2, you must either stay on `vue-debounce` v4 or migrate to the dedicated `vue2-debounce` package.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure you are using ESM `import` statements (e.g., `import vueDebounce from 'vue-debounce'`) and that your build tools are configured to handle ES modules correctly. Avoid `require('vue-debounce')`.","message":"As of v5.0.0, `vue-debounce` is published as an ES module (`type: 'module'` in package.json). This changes how it should be imported, particularly in CommonJS environments or older build setups.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"For Vue 3, directly import and register `vueDebounce`. For Vue 2, use the `vue2-debounce` package which provides the Vue 2 compatible directive directly.","message":"Vue Debounce v4.0.0 removed the `getDirective` flow, simplifying usage by separating Vue 2 and Vue 3 imports and direct directive registration. Attempts to use `getDirective` will fail.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If you need the trimmed value in your callback, manually apply `String.prototype.trim()` within your debounced function: `myFunction(value) { const trimmedValue = value.trim(); /* ... */ }`.","message":"The `trim` option/modifier, introduced in v3.0.0, only affects the internal logic for determining if an input should fire (e.g., preventing empty string callbacks). The value passed to your debounced function will *not* be automatically trimmed.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Review the `fireonempty` modifier/option usage and test its behavior. Adjust your logic or explicitly set `fireOnEmpty: true` if needed, understanding the stricter conditions for firing on empty input.","message":"The behavior of `fireonempty` was made stricter in v3.0.0 to fix a bug. If you relied on previous looser behavior, your debounced function might not fire when an input is emptied.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project uses ES module `import` syntax (`import vueDebounce from 'vue-debounce'`) and that your build environment (e.g., Webpack, Vite, Rollup) is configured to handle ES modules properly.","cause":"Attempting to import `vue-debounce` (v5+) in a CommonJS context or with a bundler configuration that does not correctly resolve ES modules.","error":"TypeError: (0 , vue_debounce__WEBPACK_IMPORTED_MODULE_0__.default) is not a function"},{"fix":"Globally: `app.directive('debounce', vueDebounce(...))` in your `main.js`/`main.ts`. Locally: `directives: { debounce: vueDebounce(...) }` in your component options, or within `<script setup>` in Vue 3 via `const vDebounce = vueDebounce(...)`.","cause":"The `v-debounce` directive has not been correctly registered with your Vue application, either globally or locally within the component.","error":"[Vue warn]: Failed to resolve directive: debounce"},{"fix":"Migrate to `vue2-debounce` for Vue 2 projects, or downgrade `vue-debounce` to v4.","cause":"Attempting to use `vue-debounce` v5+ (which is Vue 3 only) with a Vue 2 application.","error":"Cannot read properties of undefined (reading 'install')"}],"ecosystem":"npm"}