Vue Idle User Detector

Common errors

• TypeError: Vue.use is not a function

  cause 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

  cause 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

  cause 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.

Warnings

• breaking Prior 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.
• gotcha For 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.
• gotcha The `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.

Install

• npm install v-idle npm
• yarn add v-idle yarn
• pnpm add v-idle pnpm

Imports

• Vidle
  wrong:

  import { Vidle } from 'v-idle'

  correct:

  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
  wrong:

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

  correct:

  import { defineComponent } from 'vue'

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

  import { defineComponent } from 'vue'

  correct:

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

  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.

Quickstart

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.

<!-- App.vue template example -->
<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>