Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/malekim/v-idle
A Vue.js plugin to detect idle/non-active users
https://github.com/malekim/v-idle
idle loop nuxt reminders timer typescript vue vue-plugin vuejs
Last synced: 1 day ago
JSON representation
A Vue.js plugin to detect idle/non-active users
- Host: GitHub
- URL: https://github.com/malekim/v-idle
- Owner: malekim
- License: mit
- Created: 2019-08-06T21:43:02.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-18T22:51:59.000Z (7 months ago)
- Last Synced: 2024-12-25T12:06:35.555Z (9 days ago)
- Topics: idle, loop, nuxt, reminders, timer, typescript, vue, vue-plugin, vuejs
- Language: TypeScript
- Homepage: https://malekim.github.io/v-idle/
- Size: 998 KB
- Stars: 70
- Watchers: 3
- Forks: 8
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# v-idle
[](https://codecov.io/gh/malekim/v-idle)
V-idle is a universal Vue plugin compatible with Vue 2 and Vue 3 to detect idle/non-active users.
## Installation
The plugin can be installed by npm, yarn or pnpm. Alternatively it can be used through jsdelivr CDN.
### NPM
```bash
npm install v-idle --save
```
### Yarn
```bash
yarn add v-idle
```
### PNPM
```bash
pnpm add v-idle
```
### Jsdelivr CDN
Latest version of the plugin is available here:
[https://cdn.jsdelivr.net/npm/v-idle@latest/build/vidle.umd.min.js](https://cdn.jsdelivr.net/npm/v-idle@latest/build/vidle.umd.min.js)
## Basic usage
From 1.0.0 version the plugin supports vue 2 and vue 3 with the help of vue-demi package.
Starting with this version, the plugin no longer requires installation via `Vue.use()`. Simply import the 'Vidle' component where needed.
### Vue 2.6+
For Vue 2.6+, ensure you have the [@vue/composition-api](https://github.com/vuejs/composition-api) installed.
```javascript
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
Vue.use(VueCompositionAPI)
```
```javascript
import { defineComponent } from '@vue/composition-api'
import Vidle from 'v-idle'
export default defineComponent({
components: {
Vidle,
},
})
```
### Vue 2.7.2
```javascript
import { defineComponent } from 'vue'
import Vidle from 'v-idle'
export default defineComponent({
components: {
Vidle,
},
})
```
### Vue 3
```javascript
import { defineComponent } from 'vue'
import Vidle from 'v-idle'
export default defineComponent({
components: {
Vidle,
},
})
```
## Component
Inside template use v-idle component:
```html
```
It will show timer counting down from 05:00 by default.
## Options
### @idle
Type: Function
Default: none
Executes when the timer reaches 00:00
```html
```
### @remind
Type: Function
Default: none
Executes when the timer reaches time in seconds before 00:00
```html
```
### @refresh
Type: Function
Argument: object with type of event (for example 'mousemove') and key (if timer was refreshed with keyboard)
Default: none
Executes when activity is detected
```html
```
```javascript
methods: {
onrefresh(event: {
type: string
key: string | undefined
}) {
console.info(event.type)
console.info(event.key)
if (event.type === 'keydown') {
if (event.key !== undefined && event.key === 'Escape') {
console.error('Escape clicked')
}
}
},
}
```
### reminders
Type: Array
Default: empty array
Array with seconds. Each value will execute @remind
### loop
Type: Boolean
Default: false
If set to true, timer will start execution again after 00:00
```html
```
### syncKey
Type: String
Default: ''
Setting `syncKey` to a non-empty string activates the propagation of the `refresh` event across all browser tabs and windows for component instances sharing the same `syncKey`.
However, it's important to note that while the `refresh` event is synchronized, the internal timer associated with each component instance continues to count independently from the moment when the component is mounted in each tab or window. In fact, the first `refresh` event will reset timer in all the component instances.
The synchronization feature is implemented using the browser's BroadcastChannel API, which is supported by all major browsers. For environments where BroadcastChannel is not supported, such as in some older browsers, consider integrating a polyfill to ensure compatibility.
```html
```
### events
Type: Array
Default: ['mousemove', 'keypress']
Each event will break countdown.
```html
```
### wait
Type: Number
Default: 0
How many second to wait before starting countdown.
```html
```
### duration
Type: Number
Default: 60 * 5
Should be in seconds, default value is 60 * 5 seconds, so 5 minutes.
```html
```
## Example
Create a timer for 300 seconds (5 minutes) with loop, remind 10 and 15 second before 00:00 with function onremind(), wait 5 seconds before showing user the timer, execute function onidle() when the timer reaches 00:00.
```html
```
```javascript
methods: {
onidle() {
alert('You have been logged out');
},
onremind(time) {
// alert seconds remaining to 00:00
alert(time);
}
}
```
## Tests
To run tests type:
```bash
npm run test
```
To run particular test type:
```bash
npm run test -- -t "test_name"
```
## Roadmap
- Add option to show seconds timer instead of clock timer
## License
`v-idle` uses the MIT License (MIT). Please see the [license file](https://github.com/malekim/v-idle/blob/master/LICENSE) for more information.