Vue User Inactivity Detection

2.0.5 · maintenance · verified Sun Apr 19

idle-vue is a Vue.js plugin designed to detect user inactivity within a Vue 2 application. It leverages the underlying `idle-js` library to provide a reactive and integrated solution for monitoring when a user has not interacted with the application for a specified duration. The package is currently at version 2.0.5 and, as a Vue 2-specific plugin, its release cadence is likely stable, focused on maintenance rather than frequent new features, aligning with the lifecycle of Vue 2 itself. It offers three primary mechanisms for handling idle states: `onIdle` and `onActive` lifecycle hooks accessible in any Vue component, a computed property `isAppIdle` for reactive state management, and an optional `IdleView` component for a default idle overlay. A key differentiator is its flexible integration, allowing users to either provide an `eventEmitter` (a Vue instance) for hook-based responses or a Vuex `store` for state-driven reactivity, providing developers with robust options for building responsive user experiences around inactivity detection without boilerplate DOM event handling.

Common errors

```
Error: `Vue.use()` requires a plugin be passed as an argument.
```
cause Attempting to install idle-vue without correctly importing or passing the IdleVue plugin itself.

fix Ensure `import IdleVue from 'idle-vue'` is present and `Vue.use(IdleVue, ...)` is called with the imported plugin.
```
TypeError: Cannot read properties of undefined (reading 'isIdle') or 'isAppIdle' is undefined.
```
cause The `idle-vue` plugin was not initialized with a Vuex store, which is required for `isAppIdle` to be available.

fix Pass a Vuex store instance in the plugin options: `Vue.use(IdleVue, { store })` and ensure the store is provided to your root Vue instance.
```
onIdle or onActive hooks are not firing.
```
cause The `idle-vue` plugin was not initialized with an `eventEmitter` (a Vue instance) in its options, which is necessary for the hooks to function.

fix Provide an `eventEmitter` in the plugin options: `const eventsHub = new Vue(); Vue.use(IdleVue, { eventEmitter: eventsHub, ... })`.

Warnings

breaking idle-vue is designed for Vue 2 applications and is not compatible with Vue 3 due to fundamental changes in Vue's plugin API and reactivity system.
Fix: For Vue 3 projects, consider alternative libraries or implement idle detection manually using standard browser APIs.
gotcha The plugin requires either an `eventEmitter` (a Vue instance) or a Vuex `store` instance in its options. Omitting both will prevent the plugin from functioning correctly.
Fix: Ensure that the options object passed to `Vue.use(IdleVue, options)` includes either `eventEmitter: new Vue()` or `store: new Vuex.Store({...})`.
gotcha The `onIdle` and `onActive` hooks will only be invoked if an `eventEmitter` (a Vue instance) is provided in the plugin options.
Fix: To use the hooks, pass `eventEmitter: new Vue()` in the plugin options. If using a Vuex store, ensure the store is correctly configured and passed.
gotcha The `isAppIdle` computed property and the `IdleView` component will only be available if a Vuex `store` instance is provided in the plugin options.
Fix: To utilize `isAppIdle` or the `IdleView` component, pass `store: new Vuex.Store({...})` in the plugin options and ensure the store is correctly imported and provided to your root Vue instance.

Install

npm install idle-vue npm
yarn add idle-vue yarn
pnpm add idle-vue pnpm

Imports

IdleVue
wrong:
```
const IdleVue = require('idle-vue')
```
correct:
```
import IdleVue from 'idle-vue'
```
CommonJS require syntax is typically not used in modern Vue (ESM-based) projects.
Vue
wrong:
```
const Vue = require('vue')
```
correct:
```
import Vue from 'vue'
```
The global Vue instance is required to install the plugin via `Vue.use()`.
Plugin Installation
```
Vue.use(IdleVue, options)
```
idle-vue is a Vue plugin and must be installed globally with `Vue.use()` before creating the root Vue instance.

Quickstart

This quickstart demonstrates how to set up `idle-vue` using an `eventEmitter` to detect user inactivity and respond via `onIdle` and `onActive` hooks, updating the UI accordingly.

import Vue from 'vue';
import IdleVue from 'idle-vue';

// Create a new Vue instance to act as the event hub for idle-vue
const eventsHub = new new Vue();

// Install the idle-vue plugin with the event hub and an idle time of 10 seconds
Vue.use(IdleVue, {
  eventEmitter: eventsHub,
  idleTime: 10000 // 10 seconds (in milliseconds)
});

// Create the main Vue application instance
const vm = new Vue({
  el: '#app',
  data () {
    return {
      messageStr: 'Application is active.'
    };
  },
  // Define the onIdle hook to be called when the app goes idle
  onIdle() {
    this.messageStr = 'Application is idle. ZZZ...';
    console.log('User is idle!');
  },
  // Define the onActive hook to be called when the app becomes active again
  onActive() {
    this.messageStr = 'Application is active again!';
    console.log('User is active!');
  },
  template: `
    <div style="font-family: sans-serif; text-align: center; margin-top: 50px;">
      <h1>idle-vue Example</h1>
      <p>{{ messageStr }}</p>
      <p>Move your mouse or type to stay active. It will go idle after 10 seconds of inactivity.</p>
    </div>
  `
});

view raw JSON →