{"id":23419708,"url":"https://github.com/pdroll/windowevents","last_synced_at":"2025-04-09T09:17:02.588Z","repository":{"id":14104769,"uuid":"76007924","full_name":"pdroll/windowevents","owner":"pdroll","description":"Provides a unified interface for adding listeners to all window load, scroll, resize and visibility change events.","archived":false,"fork":false,"pushed_at":"2023-01-07T23:14:13.000Z","size":900,"stargazers_count":1,"open_issues_count":12,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-14T17:22:10.043Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/windowevents","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pdroll.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-09T06:23:43.000Z","updated_at":"2021-05-12T19:34:21.000Z","dependencies_parsed_at":"2023-01-11T18:44:31.854Z","dependency_job_id":null,"html_url":"https://github.com/pdroll/windowevents","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdroll%2Fwindowevents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdroll%2Fwindowevents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdroll%2Fwindowevents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdroll%2Fwindowevents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pdroll","download_url":"https://codeload.github.com/pdroll/windowevents/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008624,"owners_count":21032556,"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":[],"created_at":"2024-12-23T01:28:04.469Z","updated_at":"2025-04-09T09:17:02.572Z","avatar_url":"https://github.com/pdroll.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WindowEvents.js\nYour one stop shop for listening for all window load, scroll, resize and visibility change events.\n\nProvides a simple and unified interface for adding event listeners for 18 common and useful events including window loaded, scroll start, scroll stop, resize stop, orientation change, window becoming visible and more.\n\nThis library handles the throttling of the event listeners when needed, does not require jQuery or any other external library, and is less than 9KB in size.\n\n## Demo\n[See it in action](https://pdroll.github.io/windowevents/)\n\n## Install\nYou can install this in a couple ways:\n\n### Install and load as an NPM module\n\n```shell\nnpm install windowevents --save\n```\n\nor if you use [Yarn](https://yarnpkg.com/)\n\n```shell\nyarn add windowevents\n```\n\nLoad the library in your JS file:\n\n```javascript\nvar WindowEvents = require('windowevents');\n```\n\n### OR Install using a `\u003cscript\u003e` tag:\n\nInclude library script tag before your application JS.\n\n```html\n\u003cscript src=\"//cdn.jsdelivr.net/windowevents/latest/windowevents.min.js\"\u003e\u003c/script\u003e\n```\n\nAfter that has loaded, a  `WindowEvents` variable will be available on the `window` object.\n\n```javascript\n// WindowEvents variable is\n// already loaded for you\nconsole.log(WindowEvents);\n```\n\n## Usage\n\nFirst step is initialize the `WindowEvents` object:\n\n```javascript\nvar winEvents = new WindowEvents();\n```\n\n### Options\nYou can optionally supply an options object to the constructor:\n\n```javascript\nvar options = {\n  scrollDelay: 100,\n  resizeDelay: 350\n};\nvar winEvents = new WindowEvents(options);\n```\n#### Available options\n|    Option     | Type | Description |\n|---------------|------|-------------|\n| `scrollDelay` | int  | Number of milliseconds that the scroll events will be throttled. Default 100 |\n| `resizeDelay` | int  | Number of milliseconds that the resize events will be throttled. Default 350 |\n\n## Methods\n\n### `winEvents.on(eventName, callback)`\n\nSubscribe to a window event.\n\n```javascript\n// Subscribe to the 'scroll.stop' event\nwinEvents.on('scroll.stop', function(scrollData) {\n    doSomething(scrollData.scrollPercent)\n});\n```\n\n\n### `winEvents.once(eventName, callback)`\n\nSubscribe to an event only once.\n\n```javascript\n// Function will only fire for first time you scroll to the bottom of the page\nwinEvents.once('scroll.bottom', function(scrollData) {\n    doSomethingOnce(scrollData.scrollTop)\n});\n```\n\n### `winEvents.off(eventName)`\n\nUnsubscribe all listeners to an event:\n\n```javascript\n// unsubscribe from 'resize.stop'\nwinEvents.off('resize.stop');\n```\n\n### `winEvents.off(eventName, listenerToken)`\n\nUnsubscribe one specific listener to an event.\n\nYou'll need to save the token returned by your call to `winEvents.on()`\n\n```javascript\nvar firstListener = winEvents.on('scroll.down', function(scrollData) {\n  console.log('We are scrolling down the page');\n});\n\nvar secondListener = winEvents.on('scroll.down', function(scrollData) {\n  console.log('Another listener for scrolling down');\n});\n\n// Unsubscribe just the first Listener\nwinEvents.off('scroll.down', firstListener);\n\n// The first listener will no longer fire\n// when the window is scrolled down, but\n// the second listener will continue to work.\n```\n\n### `winEvents.off(eventName, functionReference)`\n\nYou can also unsubscribe a listener from an event by passing in the same function\nthat passed into the call to `on` or `once`\n\n```javascript\nvar myCallback = function(scrollData) {\n  console.log('We are scrolling down the page');\n}\n\nvar mySecondCallback = function(scrollData) {\n  console.log('A second listener for scrolling down');\n}\n\nwinEvents.on('scroll.down', myCallback);\nwinEvents.on('scroll.down', mySecondCallback);\n\n// Unsubscribe just the first Listener\nwinEvents.off('scroll.down', myCallback);\n\n// myCallback no longer fire\n// when the window is scrolled down, but\n// mySecondCallback will continue to work.\n```\n\n### `winEvents.getState()`\n\nImmediately get current size, scroll position, and visibility of the window. Returns an object with the following properties:\n\n- `width`\n- `height`\n- `orientation` (\"portrait\" or \"landscape\")\n- `scrollHeight`\n- `scrollTop`\n- `scrollPercent`\n- `visible`\n- `loaded` (\"loading\", \"interactive\", or \"complete\")\n\n### `winEvents.updateState()`\n\nThis method is useful when some event, other than the window being resized, causes the window to page to change scroll height or scroll position. Examples could be more content being loaded or an element being hidden or shown.\n\nReturns an object with the following properties:\n\n- `width`\n- `height`\n- `orientation` (\"portrait\" or \"landscape\")\n- `scrollHeight`\n- `scrollTop`\n- `scrollPercent`\n- `visible`\n- `loaded` (\"loading\", \"interactive\", or \"complete\")\n\n## Events\n\nThe following events are available to subscribe to:\n\n### Scroll Events\n\nAll scroll listeners will receive one parameter, an object with the following properties:\n\n- `scrollTop`\n- `scrollPercent`\n\n|   Event Name    | Description |\n|-----------------|-------------|\n| `scroll.start`  | Scrolling has started. |\n| `scroll`        | Will fire while scrolling in either direction. Will be throttled and only fire once in every interval defined in the `scrollDelay` option. |\n| `scroll.down`   | Same as `scroll`, but will only fire if scrolling down. |\n| `scroll.up`     | Same as `scroll`, but will only fire if scrolling up. |\n| `scroll.bottom` | Will fire when scrolling has reached the bottom of the page. |\n| `scroll.top`    | Will fire when scrolling has reached the top of the page. |\n| `scroll.stop`   | Scrolling has stopped. |\n\n### Resize Events\n\nAll resize listeners will receive one parameter, an object with the following properties:\n\n- `width`\n- `height`\n- `orientation` (\"portrait\" or \"landscape\")\n- `scrollHeight`\n\n|         Event Name          |   Description   |\n|-----------------------------|-----------------|\n| `resize.start`              | The window has started to be resized. |\n| `resize`                    | Will fire while the window is being resized. Will be throttled and only fire once in every interval defined in the `resizeDelay` option. |\n| `resize.orientationChange`  | Will fire when the window has been resized from portrait to landscape, or vice versa. |\n| `resize.scrollHeightChange` | Will fire when resizing has caused the `document.body.scrollHeight` to change.  |\n| `resize.stop`               | The window has stopped being resized. |\n\n### Visibility Events\n\nThese events let you know when a webpage is visible or in focus, and they rely on the [Page Visibility API](https://developer.mozilla.org/docs/Web/API/Page_Visibility_API). Unfortunately, this API [isn't supported in IE 9 or older](http://caniuse.com/#feat=pagevisibility).\n\nAll visibility listeners will receive one parameter, an object with the following property:\n\n- `visible` (`true` or `false`)\n\n|       Event Name        |   Description   |\n|-------------------------|-----------------|\n| `visibilityChange`      | The page visibility has changed. |\n| `visibilityChange.show` | The page was previously not visible and just became visible. |\n| `visibilityChange.hide` | The page was previously visible and just lost visibility. |\n\n### Load Events\n\nThese events will notify you when the DOM has been parsed and when all images and resources have finished loading. They are based on the document `readystatechange` event.\n\nAll load listeners will receive one parameter, an object with the following property:\n\n- `loaded` (\"interactive\" or \"complete\")\n\n|    Event Name      |   Description   |\n|--------------------|-----------------|\n| `load`             | There has been any change to `document.readyState`. Will fire twice on every page load. |\n| `load.interactive` | The DOM has been parsed and is ready to be interacted with. Equivalent to [jQuery's document ready](https://learn.jquery.com/using-jquery-core/document-ready/) event. |\n| `load.complete`    | All images and resources within the page have finished loading. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdroll%2Fwindowevents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpdroll%2Fwindowevents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdroll%2Fwindowevents/lists"}