Vue Debounce Directive

Common errors

• TypeError: (0 , vue_debounce__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

  cause Attempting to import `vue-debounce` (v5+) in a CommonJS context or with a bundler configuration that does not correctly resolve ES modules.
  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.

• [Vue warn]: Failed to resolve directive: debounce

  cause The `v-debounce` directive has not been correctly registered with your Vue application, either globally or locally within the component.
  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(...)`.

• Cannot read properties of undefined (reading 'install')

  cause Attempting to use `vue-debounce` v5+ (which is Vue 3 only) with a Vue 2 application.
  fix Migrate to `vue2-debounce` for Vue 2 projects, or downgrade `vue-debounce` to v4.

Warnings

• breaking 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.
  Fix: For Vue 2 projects, install `vue2-debounce` (npm i vue2-debounce) or downgrade `vue-debounce` to v4 (npm i vue-debounce@4).
• breaking 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.
  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')`.
• breaking 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.
  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.
• gotcha 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.
  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(); /* ... */ }`.
• gotcha 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.
  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.

Install

• npm install vue-debounce npm
• yarn add vue-debounce yarn
• pnpm add vue-debounce pnpm

Imports

• vueDebounce
  wrong:

  const vueDebounce = require('vue-debounce')

  correct:

  import vueDebounce from 'vue-debounce'

  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.
• DebounceOptions

  import type { DebounceOptions } from 'vue-debounce'

  Import for TypeScript type definitions to configure global debounce options.
• Vue 2 support
  wrong:

  import vueDebounce from 'vue-debounce'

  correct:

  import vueDebounce from 'vue2-debounce'

  For Vue 2 applications, use the dedicated `vue2-debounce` package. `vue-debounce` v5+ is Vue 3 only.

Quickstart

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.

import vueDebounce from 'vue-debounce';
import { createApp } from 'vue';
import App from './App.vue';

const app = createApp(App);

// Register the directive globally with custom options
app
  .directive('debounce', vueDebounce({
    lock: false, // Lock all debounced inputs by default
    defaultTime: '500ms', // Default debounce time for directives without a specified time
    listenTo: ['keyup', 'change'] // Listen to multiple events
  }))
  .mount('#app');

// In your App.vue template:
// <template>
//   <div>
//     <input v-debounce:800ms.trim="mySearchFunction" placeholder="Search..." />
//     <button v-debounce="myClickHandler">Click Me</button>
//   </div>
// </template>

// In your component script:
// export default {
//   methods: {
//     mySearchFunction(value) {
//       console.log('Debounced search for:', value);
//     },
//     myClickHandler() {
//       console.log('Debounced click!');
//     }
//   }
// }