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.
npm install vue-debounceVerified import paths — ran on the pinned version, not inferred.
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.
For Vue 2 projects, install `vue2-debounce` (npm i vue2-debounce) or downgrade `vue-debounce` to v4 (npm i vue-debounce@4).
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')`.For Vue 3, directly import and register `vueDebounce`. For Vue 2, use the `vue2-debounce` package which provides the Vue 2 compatible directive directly.
If you need the trimmed value in your callback, manually apply `String.prototype.trim()` within your debounced function: `myFunction(value) { const trimmedValue = value.trim(); /* ... */ }`.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.
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.
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(...)`.Migrate to `vue2-debounce` for Vue 2 projects, or downgrade `vue-debounce` to v4.