Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yahoo/subscribe-ui-event
Subscribe-ui-event provides a cross-browser and performant way to subscribe to browser UI Events.
https://github.com/yahoo/subscribe-ui-event
event-listener javascript ui web
Last synced: 1 day ago
JSON representation
Subscribe-ui-event provides a cross-browser and performant way to subscribe to browser UI Events.
- Host: GitHub
- URL: https://github.com/yahoo/subscribe-ui-event
- Owner: yahoo
- License: other
- Created: 2015-07-28T13:52:55.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2024-10-21T01:46:01.000Z (24 days ago)
- Last Synced: 2024-10-21T05:09:59.005Z (24 days ago)
- Topics: event-listener, javascript, ui, web
- Language: JavaScript
- Homepage:
- Size: 2 MB
- Stars: 109
- Watchers: 14
- Forks: 23
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# subscribe-ui-event
[](http://badge.fury.io/js/subscribe-ui-event)
With `subscribe-ui-event`, instead of calling multiple `window.addEventListener('scroll', eventHandler);` by different components, call `subscribe('scroll', eventHandler)`. It will only add a single event listener and dispatch event to those who subscribe to the event via [eventemitter3](https://github.com/primus/EventEmitter3).
## Install
```bash
npm install subscribe-ui-event
```
## Single Event Listener v.s. Multiple Event Listeners
Why a single event? More performant and less memory consumption.
The [jsperf ](http://jsperf.com/subscribe-v-s-addeventlistener/2) runs 10 `addEventListener` and 10 non-throttling `subscribe`, and the outcome is that the ops/sec of `subscribe` is slightly less. But in regular case, you will use throttling `subscribe`, and it will be more performant.
For 10 `addEventListener`, the difference of memory consumption between peak and trough is about 4.1K.
For 10 `subscribe`, the difference of memory consumption between peak and trough is about 1.0K.
## Other Benefits
1. Throttling by default.
2. Access `document.body.scrollTop`, `window.innerWidth` once.
3. Provide `requestAnimationFrame` throttle for high performance.
4. Be able to use events like `scrollStart` (see below) those edge events.
## API
### subscribe
```ts
subscribe(eventType: String, callback: Function, options: Object?): Subscription
```
Provide throttled version of `window` or `document` events, such like `scroll`, `resize`, `touch` and `visibilitychange` to subscribe, see below.
**Note on IE8 or the below, the throttle will be turned off because the event object is global and will be deleted for setTimeout or rAF.**
Example:
```ts
import { subscribe } from 'subscribe-ui-event';
function eventHandler (e, payload) {
// e is the native event object and
// payload is the additional information
...
}
// 50ms throttle by default
const subscription = subscribe('scroll', eventHandler);
// remove later
subscription.unsubscribe();
```
#### Optional Payload
The format of the payload is:
```js
{
type: , // could be 'scroll', 'resize' ...
// you need to pass options.enableScrollInfo = true to subscribe to get the following data
scroll: {
top: , // The scroll position, i.g., document.body.scrollTop
delta: // The delta of scroll position, it is helpful for scroll direction
},
// you need to pass options.enableResizeInfo = true to subscribe to get the following data
resize: {
width: , // The client width
height: // The client height
},
// you need to pass options.enableTouchInfo = true to subscribe to get the following data
touch: {
axisIntention: , // 'x', 'y', or ''.
startX: ,
startY: ,
deltaX: ,
deltaY:
}
}
```
#### Options
`options.throttleRate` allows of changing the throttle rate, and the default value is 50 (ms). Set 0 for no throttle. **On IE8, there will be no throttle, because throttling will use setTimeout or rAF to achieve, and the event object passed into event handler will be overwritten.**
`options.context` allows of setting the caller of callback function.
`options.useRAF = true` allows of using `requestAnimationFrame` instead of `setTimeout`.
`options.enableScrollInfo = true` allows of getting `scrollTop`.
`options.enableResizeInfo = true` allows of getting `width` and `height` of client.
`options.enableTouchInfo = true` allows of getting touch information (see above).
`eventType` could be one of the following:
1. scroll - window.scoll
2. scrollStart - The start of window.scoll
3. scrollEnd - The end of window.scoll
4. resize - window.resize
5. resizeStart - The start window.resize
6. resizeEnd - The end window.resize
7. visibilitychange - document.visibilitychange (IE8 doesn't support)
8. touchmoveStart - The start of window.touchmove
9. touchmoveEnd - The end of window.touchmove
10. touchmove - window.touchmove
11. touchstart - window.touchstart
12. touchend - window.touchend
`options.eventOptions`: An options object that specifies characteristics about the event listener (if passive event is supported by the browser)
### unsubscribe
```js
unsubscribe(eventType: String, callback: Function): Void
```
Unsubscribe to an event listener, we suggest you use `subscription.unsubscribe()`, because it may accidentally unsubscribe those events having the same `eventType` and `callback`, but different `throttleRate`.
## Credits
- This library runs full browser test suite using Sauce Labs.
## License
This software is free to use under the BSD license.
See the [LICENSE file](./LICENSE.md) for license text and copyright information.