Vue-Wait: Global Loading Management

1.5.3 · active · verified Tue Apr 21

Vue-Wait is a Vue plugin designed for comprehensive global loading state management within Vue applications, optionally integrating with Vuex. It simplifies the handling of multiple concurrent loading processes, preventing UI conflicts and providing clear visual feedback to users. The current stable version, 1.5.3, includes important updates like Vue 3 support, released in v1.5.0, demonstrating ongoing maintenance and adaptability to the evolving Vue ecosystem. The library distinguishes itself by offering both a declarative component (`<v-wait>`) and a directive (`v-wait`) for displaying loading indicators, alongside a programmatic API (`$wait.start()`, `$wait.end()`) for granular control over individual loading states. Additionally, it provides features for progress indication and configurable Vuex integration, making it a flexible solution for various application sizes and complexities. Its core idea relies on an array-based system to track active wait states, making it intuitive to manage.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'start') (or similar for $wait)
```
cause The VueWait plugin was not correctly registered with the Vue instance, or the `wait` option was omitted in Vue 2.

fix For Vue 2, ensure `new Vue({ ..., wait: new VueWait(), ... })` is present. For Vue 3, ensure `app.use(createVueWait())` is called after `createApp()`.
```
Unknown custom element: <v-wait> - did you register the component correctly?
```
cause The `<v-wait>` component registration was disabled or the component name was customized without updating usage.

fix Ensure `registerComponent: true` (which is the default) in the VueWait options. If `componentName` was changed, update your template accordingly (e.g., `<my-loader>`).

Warnings

breaking Vue 3 applications require using the `createVueWait` named export for plugin instantiation, replacing the default export approach used for Vue 2. The plugin registration also changes from `new Vue({ wait: new VueWait() })` to `app.use(createVueWait())`.
Fix: For Vue 3, import `createVueWait` as a named export and use `app.use(createVueWait())`. For Vue 2, import `VueWait` as a default export and instantiate it within the Vue instance options: `new Vue({ wait: new VueWait() })`.
breaking The method to check if a process is waiting was renamed from `isWaiting(waiter)` to `is(waiter)` to reduce code verbosity.
Fix: Replace all calls to `this.$wait.isWaiting('processName')` with `this.$wait.is('processName')`. An alias `waiting(waiter)` was added in v1.3.0.
gotcha When integrating with Vuex, `useVuex` must be explicitly set to `true` in the VueWait plugin options. It defaults to `false`.
Fix: Initialize VueWait with `{ useVuex: true }`: `new VueWait({ useVuex: true })` or `createVueWait({ useVuex: true })`.
gotcha TypeScript users might encounter errors like 'Property '$wait' does not exist on type 'Vue'' because Vue-Wait adds a global property that TypeScript doesn't automatically recognize.
Fix: Add a declaration file (e.g., `vue-wait.d.ts`) to augment the Vue instance type: ```typescript declare module '@vue/runtime-core' { interface ComponentCustomProperties { $wait: import('vue-wait').VueWaitInstance; } } // For Vue 2 (if not using @vue/runtime-core): declare module 'vue/types/vue' { interface Vue { $wait: import('vue-wait').VueWaitInstance; } } ```

Install

npm install vue-wait npm
yarn add vue-wait yarn
pnpm add vue-wait pnpm

Imports

VueWait
wrong:
```
import { VueWait } from 'vue-wait'
```
correct:
```
import VueWait from 'vue-wait'
```
For Vue 2 applications, `VueWait` is a default export used with `Vue.use()`.
createVueWait
wrong:
```
import createVueWait from 'vue-wait'
```
correct:
```
import { createVueWait } from 'vue-wait'
```
Since v1.5.0, Vue 3 applications use `createVueWait` as a named export for plugin instantiation.

v-wait

<!-- Component usage -->
<v-wait for="processName">
  <template #waiting>Loading...</template>
  Content
</v-wait>

<!-- Directive usage -->
<button v-wait:click="'saveData'">Save</button>

The `<v-wait>` component and `v-wait` directive are registered globally when the plugin is installed with `Vue.use()` or `app.use()`.

Quickstart

This quickstart demonstrates the setup of Vue-Wait in a Vue 3 application, showing how to instantiate and register the plugin globally. It also includes commented-out example Vue component code to illustrate how to use the `<v-wait>` component and the `$wait` service to manage and display loading states for an asynchronous operation.

import { createApp } from 'vue'
import { createVueWait } from 'vue-wait'
import App from './App.vue'

const VueWait = createVueWait()

const app = createApp(App)
app.use(VueWait)
app.mount('#app')

// Example component usage:
// <template>
//   <v-wait for="my list is to load">
//     <template slot="waiting">
//       <div>Loading the list...</div>
//     </template>
//     <ul>
//       <li v-for="item in myList" :key="item">{{ item }}</li>
//     </ul>
//   </v-wait>
// </template>

// <script>
// export default {
//   data() {
//     return {
//       myList: []
//     }
//   },
//   async created() {
//     this.$wait.start('my list is to load');
//     // Simulate an async fetch
//     await new Promise(resolve => setTimeout(resolve, 2000));
//     this.myList = ['Item 1', 'Item 2', 'Item 3'];
//     this.$wait.end('my list is to load');
//   },
// };
// </script>

view raw JSON →