v-idle

library1.0.3jsnpmunverified

V-idle is a universal Vue plugin (now component-based) designed to detect inactive users across both Vue 2 and Vue 3 applications. The current stable version is v1.0.3, with recent updates indicating an active maintenance cadence focused on bug fixes and compatibility. Key differentiators include its seamless support for both Vue 2 and Vue 3 environments via `vue-demi`, eliminating the need for `Vue.use()` for plugin installation since v1.0.0. It offers flexible idle event detection, configurable reminder timings, and a unique `syncKey` feature for synchronizing activity across multiple browser tabs using the BroadcastChannel API, ensuring consistent idle state management in complex applications. This library ships with TypeScript definitions for improved developer experience.

web-framework

npm install v-idle

github ↗package ↗

INSTALL

IMPORT

SIG · V-IDLE

v-idle

web-frameworkjavascriptv1.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Vidle

✓ import Vidle from 'v-idle'

✗ import { Vidle } from 'v-idle'

As of v1.0.0, Vidle is a default export and used directly as a component. It no longer requires global Vue.use() plugin registration.

defineComponent

✓ import { defineComponent } from 'vue'

✗ import { defineComponent } from '@vue/composition-api'

For Vue 2.7 and Vue 3 projects, `defineComponent` should be imported directly from 'vue'.

defineComponent

✓ import { defineComponent } from '@vue/composition-api'

✗ import { defineComponent } from 'vue'

For Vue 2.6 projects utilizing the Composition API, `defineComponent` must be imported from '@vue/composition-api'. Ensure `VueCompositionAPI` is globally installed via `Vue.use()`.

VueCompositionAPI

✓ import VueCompositionAPI from '@vue/composition-api'

This import is typically used in Vue 2.6+ setups alongside `Vue.use(VueCompositionAPI)` to enable Composition API support, which `v-idle` relies on for its universal compatibility.

This example demonstrates basic integration of the `Vidle` component within a Vue 3 setup, showcasing how to handle `@idle` and `@refresh` events, configure `reminders`, `events` to track, and use `syncKey` for cross-tab synchronization. The `wait` prop is set to a short duration for quick testing.

<template> <div> <h1>v-idle Demo</h1> <p>Idle Count: {{ idleCount }}</p> <p>Refresh Count: {{ refreshCount }}</p> <p>Last Activity: {{ lastActivity || 'None yet' }}</p> <Vidle @idle="onIdle" @refresh="onRefresh" :reminders="[5, 10]" :events="['mousemove', 'keypress', 'click']" :wait="30" syncKey="my-app-idle-sync" /> <p>Move mouse, click, or press keys to reset the timer.</p> <p>An idle event will fire after 30 seconds of inactivity, with reminders at 5 and 10 seconds remaining.</p> <p>The `syncKey` prop will synchronize activity across tabs sharing the same key.</p> </div> </template> <script lang="typescript"> import { defineComponent, ref } from 'vue'; import Vidle from 'v-idle'; export default defineComponent({ components: { Vidle, }, setup() { const idleCount = ref(0); const refreshCount = ref(0); const lastActivity = ref(''); const onIdle = () => { idleCount.value++; console.log('User is idle!'); }; const onRefresh = (event: { type: string; key: string | undefined }) => { refreshCount.value++; lastActivity.value = event.type + (event.key ? ` (${event.key})` : ''); console.log('User activity detected:', event.type, event.key); }; return { idleCount, refreshCount, lastActivity, onIdle, onRefresh, }; }, }); </script>

Debug

Known issues

breakingPrior to v1.0.0, `v-idle` was installed as a Vue plugin via `Vue.use(Vidle)`. As of v1.0.0, `v-idle` is no longer a plugin and must be imported directly as a component (`import Vidle from 'v-idle'`) and registered in your component's `components` option.

fix

Remove `Vue.use(Vidle)` calls from your application entry point. Update components to import `Vidle` directly (`import Vidle from 'v-idle'`) and ensure it is listed in the `components` option of any Vue component where it is used.

affects: >=1.0.0

gotchaFor Vue 2.6 projects, utilizing the Composition API (and therefore `v-idle`'s cross-version compatibility) requires explicit installation of the `@vue/composition-api` package and registering it with `Vue.use(VueCompositionAPI)` in your main Vue entry file.

fix

Ensure `@vue/composition-api` is installed (`npm install @vue/composition-api`) and add `import VueCompositionAPI from '@vue/composition-api'; Vue.use(VueCompositionAPI);` to your application's main JavaScript/TypeScript file.

affects: <3.0.0

gotchaThe `syncKey` feature, introduced in v1.0.1 for synchronizing the refresh event across browser tabs, relies on the browser's `BroadcastChannel` API. This API might not be supported in older browsers, preventing the synchronization feature from working as expected in those environments.

fix

For environments lacking native `BroadcastChannel` support (e.g., some older browsers), integrate a polyfill for `BroadcastChannel` to ensure the cross-tab synchronization functions correctly.

affects: >=1.0.1

Errors

Common errors & fixes

TypeError: Vue.use is not a function

Attempting to install `v-idle` as a plugin using `Vue.use()` after v1.0.0.

fix

Remove `Vue.use(Vidle)` calls. `v-idle` is now a component; import it directly (`import Vidle from 'v-idle'`) and register it in your component's `components` option.

[Vue warn]: Failed to resolve component: Vidle

The `Vidle` component has not been correctly registered in the parent Vue component's `components` option, or the import path is incorrect.

fix

Ensure `Vidle` is imported correctly (`import Vidle from 'v-idle'`) and explicitly registered within the `components` option of the Vue component where it's being used, e.g., `{ components: { Vidle } }`.

TypeError: Cannot read properties of undefined (reading 'use') at <anonymous>:1:5

When using `v-idle` in Vue 2.6+ with Composition API, `@vue/composition-api` has not been correctly installed and registered globally via `Vue.use(VueCompositionAPI)`.

fix

For Vue 2.6 projects, install `@vue/composition-api` (`npm install @vue/composition-api`) and ensure `Vue.use(VueCompositionAPI)` is called in your application's entry file before mounting your root Vue instance.

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

@vue/composition-apirequiredRequired for Vue 2.6+ projects to enable Composition API features, which v-idle leverages internally for cross-version compatibility.

vuerequiredPeer dependency for core Vue functionality, supporting both Vue 2.x and 3.x.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/malekim/v-idle ↗

packagehttps://www.npmjs.com/package/v-idle ↗