{"id":20038506,"url":"https://github.com/yahoo/subscribe-ui-event","last_synced_at":"2025-05-15T16:07:39.050Z","repository":{"id":35564808,"uuid":"39836769","full_name":"yahoo/subscribe-ui-event","owner":"yahoo","description":"Subscribe-ui-event provides a cross-browser and performant way to subscribe to browser UI Events.","archived":false,"fork":false,"pushed_at":"2025-04-01T13:51:18.000Z","size":2513,"stargazers_count":110,"open_issues_count":8,"forks_count":24,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-07T21:14:54.799Z","etag":null,"topics":["event-listener","javascript","ui","web"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yahoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-07-28T13:52:55.000Z","updated_at":"2025-03-05T22:25:41.000Z","dependencies_parsed_at":"2023-09-25T23:22:38.534Z","dependency_job_id":"dcf6e9ab-dfd6-4376-b460-719271a5de20","html_url":"https://github.com/yahoo/subscribe-ui-event","commit_stats":{"total_commits":298,"total_committers":21,"mean_commits":14.19047619047619,"dds":0.4093959731543624,"last_synced_commit":"b9bb9eb86c1974c69dbbd7301a61897f9d950797"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fsubscribe-ui-event","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fsubscribe-ui-event/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fsubscribe-ui-event/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fsubscribe-ui-event/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yahoo","download_url":"https://codeload.github.com/yahoo/subscribe-ui-event/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374475,"owners_count":22060611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["event-listener","javascript","ui","web"],"created_at":"2024-11-13T10:29:35.984Z","updated_at":"2025-05-15T16:07:39.034Z","avatar_url":"https://github.com/yahoo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# subscribe-ui-event\n\n[![npm version](https://badge.fury.io/js/subscribe-ui-event.svg)](http://badge.fury.io/js/subscribe-ui-event)\n![github actions](https://github.com/yahoo/subscribe-ui-event/actions/workflows/test.js.yml/badge.svg)\n\nWith `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).\n\n## Install\n\n```bash\nnpm install subscribe-ui-event\n```\n\n## Single Event Listener v.s. Multiple Event Listeners\n\nWhy a single event? More performant and less memory consumption.\n\nThe [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.\n\n![comparison](https://cloud.githubusercontent.com/assets/2044960/9611594/6167df1c-5095-11e5-8abc-c81ff4d13ce6.png)\n\nFor 10 `addEventListener`, the difference of memory consumption between peak and trough is about 4.1K.\n\n![addEventListener](https://cloud.githubusercontent.com/assets/2044960/9611614/778bc452-5095-11e5-80d9-be9379df9956.png)\n\nFor 10 `subscribe`, the difference of memory consumption between peak and trough is about 1.0K.\n\n![subscribe](https://cloud.githubusercontent.com/assets/2044960/9611619/7c293652-5095-11e5-8d27-29a0d2d167cc.png)\n\n## Other Benefits\n\n1.  Throttling by default.\n2.  Access `document.body.scrollTop`, `window.innerWidth` once.\n3.  Provide `requestAnimationFrame` throttle for high performance.\n4.  Be able to use events like `scrollStart` (see below) those edge events.\n\n## API\n\n### subscribe\n\n```ts\nsubscribe(eventType: String, callback: Function, options: Object?): Subscription\n```\n\nProvide throttled version of `window` or `document` events, such like `scroll`, `resize`, `touch` and `visibilitychange` to subscribe, see below.\n\n**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.**\n\nExample:\n\n```ts\nimport { subscribe } from 'subscribe-ui-event';\nfunction eventHandler (e, payload) {\n    // e is the native event object and\n    // payload is the additional information\n    ...\n}\n// 50ms throttle by default\nconst subscription = subscribe('scroll', eventHandler);\n// remove later\nsubscription.unsubscribe();\n```\n\n#### Optional Payload\n\nThe format of the payload is:\n\n```js\n{\n    type: \u003cString\u003e, // could be 'scroll', 'resize' ...\n    // you need to pass options.enableScrollInfo = true to subscribe to get the following data\n    scroll: {\n        top: \u003cNumber\u003e, // The scroll position, i.g., document.body.scrollTop\n        delta: \u003cNumber\u003e // The delta of scroll position, it is helpful for scroll direction\n    },\n    // you need to pass options.enableResizeInfo = true to subscribe to get the following data\n    resize: {\n        width: \u003cNumber\u003e, // The client width\n        height: \u003cNumber\u003e // The client height\n    },\n    // you need to pass options.enableTouchInfo = true to subscribe to get the following data\n    touch: {\n        axisIntention: \u003cString\u003e, // 'x', 'y', or ''.\n        startX: \u003cNumber\u003e,\n        startY: \u003cNumber\u003e,\n        deltaX: \u003cNumber\u003e,\n        deltaY: \u003cNumber\u003e\n    }\n}\n```\n\n#### Options\n\n`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.**\n\n`options.context` allows of setting the caller of callback function.\n\n`options.useRAF = true` allows of using `requestAnimationFrame` instead of `setTimeout`.\n\n`options.enableScrollInfo = true` allows of getting `scrollTop`.\n\n`options.enableResizeInfo = true` allows of getting `width` and `height` of client.\n\n`options.enableTouchInfo = true` allows of getting touch information (see above).\n\n`eventType` could be one of the following:\n\n1.  scroll - window.scoll\n2.  scrollStart - The start of window.scoll\n3.  scrollEnd - The end of window.scoll\n4.  resize - window.resize\n5.  resizeStart - The start window.resize\n6.  resizeEnd - The end window.resize\n7.  visibilitychange - document.visibilitychange (IE8 doesn't support)\n8.  touchmoveStart - The start of window.touchmove\n9.  touchmoveEnd - The end of window.touchmove\n10. touchmove - window.touchmove\n11. touchstart - window.touchstart\n12. touchend - window.touchend\n\n`options.eventOptions`: An options object that specifies characteristics about the event listener (if passive event is supported by the browser)\n\n### unsubscribe\n\n```js\nunsubscribe(eventType: String, callback: Function): Void\n```\n\nUnsubscribe 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`.\n\n## Credits\n\n-   This library runs full browser test suite using Sauce Labs.\n\n## License\n\nThis software is free to use under the BSD license.\nSee the [LICENSE file](./LICENSE.md) for license text and copyright information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Fsubscribe-ui-event","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyahoo%2Fsubscribe-ui-event","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Fsubscribe-ui-event/lists"}