{"id":28391382,"url":"https://github.com/wearebraid/observer-registry","last_synced_at":"2025-07-29T16:05:05.109Z","repository":{"id":57154767,"uuid":"180167234","full_name":"wearebraid/observer-registry","owner":"wearebraid","description":"An IntersectionObserver utility for notifying callbacks when an element's intersection changes.","archived":false,"fork":false,"pushed_at":"2019-04-10T15:21:09.000Z","size":65,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-15T18:04:16.524Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wearebraid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-08T14:30:14.000Z","updated_at":"2022-01-26T12:59:42.000Z","dependencies_parsed_at":"2022-09-06T20:51:51.630Z","dependency_job_id":null,"html_url":"https://github.com/wearebraid/observer-registry","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/wearebraid/observer-registry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearebraid%2Fobserver-registry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearebraid%2Fobserver-registry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearebraid%2Fobserver-registry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearebraid%2Fobserver-registry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wearebraid","download_url":"https://codeload.github.com/wearebraid/observer-registry/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearebraid%2Fobserver-registry/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267716544,"owners_count":24133160,"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","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-05-31T09:11:51.661Z","updated_at":"2025-07-29T16:05:04.752Z","avatar_url":"https://github.com/wearebraid.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Observer Registry\n-----------------\n\n[![CircleCI](https://circleci.com/gh/wearebraid/observer-registry.svg?style=svg)](https://circleci.com/gh/wearebraid/observer-registry)\n\nObserver Registry is a lightweight (1.8KB or 709B gzip!) library to make interacting with the\n[Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)\na little more pleasant by allowing you to specify callbacks for each element you\nare observing. ObserverRegistry will handle instantiating any\n`IntersectionObservers` while using the fewest instances to accomplish your\nobservation needs.\n\n## Installation\n\nInstall the package from npm:\n\n```sh\nnpm install observer-registry\n```\n\n## Usage\n\nThe first step to using ObserverRegistry is creating an instance. You should\nreally only ever need once instance of the `ObserverRegistry`, it will maintain\nany and all instances of `IntersectionObserver` in order to give you the\ndesired results.\n\n### Observing an element\n\nObserving an element is simple, you just pass the element and a callback to be\nnotified when it changes.\n\n```js\nimport ObserverRegistry from 'observer-registry'\n\nconst observer = new ObserverRegistry()\nconst element = document.getElementById('my-element')\n\nobserver.addElement(element, event =\u003e alert('element visibility changed!'))\n```\n\nYou can pass as many elements into an instance of  `ObserverRegistry` as you want:\n\n```js\nconst callback = () =\u003e alert('An element has been seen!')\nconst header = document.getElementById('header')\nconst menu = document.getElementById('menu')\nconst body = document.getElementById('body')\nconst footnote = document.getElementById('footnote')\nconst footer = document.getElementById('footer')\n// Or call addElement as many times as you want (with chaining)\nobserver.addElement(header, callback).addElement(menu, callback)\n// You can register an array of elements\nobserver.addElement([body footnote, footer], callback)\n// Or with a NodeList\nobserver.addElement(document.querySelectorAll('.pictures'), callback)\n```\n\n### Removing an element\n\nTo stop watching for intersection events on an element remove it from the registry.\n\n```js\nobserver.removeElement(element)\n```\n\n### Observe an element with custom margins\n\nThe `addElement` method accepts a third argument `options`. Included in the\nlist of available options are the three options provided by the native\n`IntersectionObserver` class `root`, `rootMargin`, and `threshold`. For a full\nlist of options see the table below.\n\n```js\nobserver.addElement(element, () =\u003e alert('Using a margin'), {\n    rootMargin: '-100px'\n})\n```\n\n### Observe an element with custom root\n\n```js\nconst element = document.getElementById('my-element')\nobserver.addElement(element, () =\u003e `element within margin!`, {\n    root: document.getElementById('my-scroll-window')\n})\n```\n### Observe only once\n\nPerfect for times when you only need to know when an item comes into view, you\ncan choose to automatically remove an element after its first observed event.\nThis is ideal for things like lazy loading images or performing entrance\nanimations on scroll where you don't need the effect to be repeated.\n\n```js\nobserver.addElement(element, () =\u003e alert('do this once!'), { once: true })\n```\n\n## `addElement` options\n\nThe third argument of `addElement` can be an options object.\n\nKey         | Description                       | Default Value\n------------|-----------------------------------|--------------\nonce        | Only trigger the callback once    | `false`\nroot        | `IntersectionObserver` root       | `null` (binds to the viewport)\nrootMargin  | `IntersectionObserver` rootMargin | `0px`\nthreshold   | `IntersectionObserver` threshold  | `0.0`\n\n## Limitations\n\nThere are a few known limitations, happy to accept pull requests for these or\nany others you might find.\n\n### One instance of each element\n\nCurrently it is only possible for any given element to be observed by one\nIntersectionObserver meaning that if the same element is registered twice, the\nfirst registered callback will be called.\n\n```js\nconst element = document.getElementById('my-element')\nobserver.addElement(element, event =\u003e alert(`element is${event.visibility ? ' ' : ' not '}visible`))\nobserver.addElement(element, event =\u003e alert('do some other activity'))\n// alert(`element is visible`)\n```\n\n### `IntersectionObserver` support\n\nTruth of the matter is that IntersectionObserver does not have spectacular\n[browser support](https://caniuse.com/#search=intersectionobserver) (lookin' at you Safari).\nSo depending on your needs, this utility may require a polyfill. The good news\nis that w3c has [provided one](https://github.com/w3c/IntersectionObserver/tree/master/polyfill).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwearebraid%2Fobserver-registry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwearebraid%2Fobserver-registry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwearebraid%2Fobserver-registry/lists"}