# subscribe-ui-event

> A single, throttle built-in solution to subscribe to browser UI Events.

Latest version **3.0.0** (published 2024-12-16) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install subscribe-ui-event
pnpm add subscribe-ui-event
yarn add subscribe-ui-event
bun add subscribe-ui-event
```

## Health

**Score 48/100 (D)** — status: stable.

Positive: has types package; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2024-12-16 |
| First published | 2015-07-30 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | separate (@types/subscribe-ui-event) |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 42.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 108 |
| Author | Hank Hsiao |
| Maintainers | redonkulus, src-code, kaesonho, hankhsiao, roderickhsiao |
| Keywords | addEventListener, browser, events, requestAnimationFrame, resize, scroll, subscribe, throttle |

## Links

- npm: https://www.npmjs.com/package/subscribe-ui-event
- Repository: https://github.com/yahoo/subscribe-ui-event
- Homepage: https://github.com/yahoo/subscribe-ui-event#readme
- Issues: https://github.com/yahoo/subscribe-ui-event/issues
- npm.io page: https://npm.io/package/subscribe-ui-event

## Dependencies (2)

- [raf](https://npm.io/package/raf.md) ^3.0.0
- [eventemitter3](https://npm.io/package/eventemitter3.md) ^5.0.0

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 3.0.0 (latest) — 2024-12-16
- 2.0.7 — 2020-08-19
- 2.0.6 — 2020-03-02
- 2.0.5 — 2018-11-21
- 2.0.4 — 2018-09-24
- 2.0.3 — 2018-07-20
- 2.0.2 — 2018-06-05
- 2.0.1 — 2018-05-11
- 2.0.0 — 2018-05-10
- 1.1.2 — 2018-05-10
- 1.1.1 — 2018-01-02
- 1.1.0 — 2017-12-20
- 1.0.14 — 2016-09-22
- 1.0.13 — 2016-08-05
- 1.0.12 — 2016-05-24
- … 28 more at https://npm.io/package/subscribe-ui-event/versions

## README

# subscribe-ui-event

[![npm version](https://badge.fury.io/js/subscribe-ui-event.svg)](http://badge.fury.io/js/subscribe-ui-event)
![github actions](https://github.com/yahoo/subscribe-ui-event/actions/workflows/test.js.yml/badge.svg)

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.

![comparison](https://cloud.githubusercontent.com/assets/2044960/9611594/6167df1c-5095-11e5-8abc-c81ff4d13ce6.png)

For 10 `addEventListener`, the difference of memory consumption between peak and trough is about 4.1K.

![addEventListener](https://cloud.githubusercontent.com/assets/2044960/9611614/778bc452-5095-11e5-80d9-be9379df9956.png)

For 10 `subscribe`, the difference of memory consumption between peak and trough is about 1.0K.

![subscribe](https://cloud.githubusercontent.com/assets/2044960/9611619/7c293652-5095-11e5-8d27-29a0d2d167cc.png)

## 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: <String>, // could be 'scroll', 'resize' ...
    // you need to pass options.enableScrollInfo = true to subscribe to get the following data
    scroll: {
        top: <Number>, // The scroll position, i.g., document.body.scrollTop
        delta: <Number> // 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: <Number>, // The client width
        height: <Number> // The client height
    },
    // you need to pass options.enableTouchInfo = true to subscribe to get the following data
    touch: {
        axisIntention: <String>, // 'x', 'y', or ''.
        startX: <Number>,
        startY: <Number>,
        deltaX: <Number>,
        deltaY: <Number>
    }
}
```

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

---
_Source: https://npm.io/package/subscribe-ui-event · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._