Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thierrymichel/vue-aware
Optimized and easy way to manage events across Vue.js components.
https://github.com/thierrymichel/vue-aware
events plugin vue vuejs
Last synced: 10 days ago
JSON representation
Optimized and easy way to manage events across Vue.js components.
- Host: GitHub
- URL: https://github.com/thierrymichel/vue-aware
- Owner: thierrymichel
- License: unlicense
- Created: 2019-06-29T10:52:02.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T07:03:35.000Z (almost 2 years ago)
- Last Synced: 2024-10-14T15:31:42.759Z (24 days ago)
- Topics: events, plugin, vue, vuejs
- Language: TypeScript
- Homepage:
- Size: 2.72 MB
- Stars: 6
- Watchers: 3
- Forks: 0
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# vue-aware
> Optimized and easy way to manage events across Vue.js components.
[](https://www.npmjs.com/package/vue-aware)
[](https://circleci.com/gh/thierrymichel/vue-aware/tree/master)
[](https://coveralls.io/github/thierrymichel/vue-aware?branch=master)
[](http://commitizen.github.io/cz-cli/)
[](https://conventionalcommits.org)
[](https://github.com/thierrymichel/vue-aware/blob/master/UNLICENSE)
## Description
`vue-aware` allows your components to easily listen to "common global" events such as:
- scroll
- viewport resize
- appear on viewport
- request animation frame
Another kind of bus event?
What makes `vue-aware` special is how it manages events for you.
`vue-aware` will create as **LESS** listeners as possible and **ONLY** when some components need it!
Which is good performance wise…
---
## Installation
```sh
npm install --save vue-aware
```
### Import
```js
import Vue from 'vue';
import VueAware from 'vue-aware';
Vue.use(VueAware);
```
### Browser
```html
```
> `vue-aware` should be auto-installed. If not, use `Vue.use(VueAware)`.
## Usage
### General
1. Simply add the `v-aware` directive to your element(s).
2. Define a handler for an event (`appear`, `raf`, `scroll`, `viewport`):
- `@[event]="handler"` or
- `v-on:[event]="handler"` or
- `v-aware="{ [event]: { callback: handler } }"`
🚨Components (vs elements) only accept `callback` property with `v-aware` directive (`@` or `v-on` won't work)
> Note: `callback` property has precedence over `@` or `v-on` directive…
#### Example (scroll)
```html
```
```html
```
```html
```
### Appear
> `appear` uses the [IntersectionObserver API](http://caniuse.com/#feat=intersectionobserver). If it is incompatible with your browser support, you can [polyfill](https://github.com/w3c/IntersectionObserver/tree/master/polyfill) it.
`appear` will let you know if your element is:
- partially in viewport
- fully in viewport
- positionned on top, bottom or center of the viewport
Like `IntersectionObserver`, it accepts options:
- **root** (`HTMLElement`, default is browser viewport)
- **rootMargin** (CSS margin prop, with `%` or `px`, default is `0px 0px 0px 0px`)
- **threshold** (related to target's visibility, `number` or `number[]`, default is `[0, 1]`)
and an extra one:
- **once** (your callback is only trigger once, default `false`)
#### Example
```html
```
```js
export default {
methods: {
appearHandler(isInViewport, isFullyInViewport, position, context) {},
},
};
```
### Raf (requestAnimationFrame)
Use [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) to trigger your handler.
There is no options.
#### Example
```html
```
```js
export default {
methods: {
rafHandler(delta, now, context) {},
},
};
```
### Scroll
Gives you the scroll position (`x` and `y`).
You can throttle or debounce it ([read more](https://css-tricks.com/the-difference-between-throttling-and-debouncing/)).
#### Example
```html
```
```js
export default {
methods: {
scrollHandler(scrollX, scrollY, context) {},
},
};
```
### Viewport
When a window resize is detected.
It gives you the width and height of the viewport + ratio (width/height).
You can throttle or debounce it ([read more](https://css-tricks.com/the-difference-between-throttling-and-debouncing/)).
By default, it is throttled (`150ms`).
#### Example
```html
```
```js
export default {
methods: {
viewportHandler(width, height, ratio, context) {},
},
};
```
---
## How to contribute
If you want to report a bug or if you just want to request for a new feature/improvement, please **follow [those instructions](CONTRIBUTING.md) before**.
Thanks for taking time to contribute to `vue-aware` :tada: :+1: