{"id":13672905,"url":"https://github.com/karl-run/react-bottom-scroll-listener","last_synced_at":"2025-05-15T18:04:46.736Z","repository":{"id":22604859,"uuid":"96810319","full_name":"karl-run/react-bottom-scroll-listener","owner":"karl-run","description":"A simple listener component that invokes a callback when the webpage is scrolled to the bottom.","archived":false,"fork":false,"pushed_at":"2025-01-22T06:57:11.000Z","size":6971,"stargazers_count":152,"open_issues_count":4,"forks_count":15,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-08T00:36:03.490Z","etag":null,"topics":["bottom","listener","react","scroll"],"latest_commit_sha":null,"homepage":"https://karl-run.github.io/react-bottom-scroll-listener","language":"TypeScript","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/karl-run.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-07-10T18:44:48.000Z","updated_at":"2025-02-23T07:58:36.000Z","dependencies_parsed_at":"2023-11-13T13:27:23.800Z","dependency_job_id":"ebefc867-4b13-43a0-9d46-5fa98549e209","html_url":"https://github.com/karl-run/react-bottom-scroll-listener","commit_stats":{"total_commits":88,"total_committers":11,"mean_commits":8.0,"dds":0.2954545454545454,"last_synced_commit":"66e5ebd4f3c427b8459063d53359dc23e04f66af"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karl-run%2Freact-bottom-scroll-listener","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karl-run%2Freact-bottom-scroll-listener/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karl-run%2Freact-bottom-scroll-listener/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karl-run%2Freact-bottom-scroll-listener/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karl-run","download_url":"https://codeload.github.com/karl-run/react-bottom-scroll-listener/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247569103,"owners_count":20959758,"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":["bottom","listener","react","scroll"],"created_at":"2024-08-02T09:01:56.125Z","updated_at":"2025-04-06T23:52:01.880Z","avatar_url":"https://github.com/karl-run.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# react-bottom-scroll-listener [![npm](https://img.shields.io/npm/dm/react-bottom-scroll-listener.svg)](https://www.npmjs.com/package/react-bottom-scroll-listener) [![NPM version](https://img.shields.io/npm/v/react-bottom-scroll-listener.svg?style=flat)](https://www.npmjs.com/package/react-bottom-scroll-listener) [![npm bundle size (minified)](https://img.shields.io/bundlephobia/minzip/react-bottom-scroll-listener.svg)](https://github.com/karl-run/react-bottom-scroll-listener)\n\nA simple **React hook** and **React component** that lets you listen for when you have scrolled to the bottom.\n\n### Window\n\n![Example](./docs/example.gif)\n\n### Container\n\n![Example](./docs/example_inner.gif)\n\n## Installation\n\nnpm:\n`npm install react-bottom-scroll-listener`\n\nyarn:\n`yarn add react-bottom-scroll-listener`\n\n## Migrating to V5\n\nVersion 5 is only a refactor for the hook to use an options parameter, instead\nof relying of function parameters which were starting to get out of hand.\n\n#### If you are using the component, there are no breaking changes\n\nIf your hook looks like this:\n\n```tsx\nuseBottomScrollListener(callback, 0, 200, undefined, true);\n```\n\nYou will have to change it to use the options parameter:\n\n```\nuseBottomScrollListener(callback, {\n  offset: 100,\n  debounce: 0,\n  triggerOnNoScroll: true\n})\n```\n\nRemember that you can omit any values that are using the defaults! The defaults are ase following:\n\n```\n  offset: 0,\n  debounce: 200,\n  debounceOptions: { leading: true },\n  triggerOnNoScroll: false,\n```\n\nSo for the average use case, you are probably only setting one of these values, so your hook\nmight look like this:\n\n```\nuseBottomScrollListener(callback, { triggerOnNoScroll: true })\n```\n\nYou can refer to the Usage-section for more details.\n\n## Usage\n\n### Hook\n\n[Full example](/example/src/HookExample.js)\n\n#### On bottom of entire screen\n\nUse the hook in any functional component, the callback will be invoked\nwhen the user scrolls to the bottom of the document\n\n```jsx\nimport { useBottomScrollListener } from 'react-bottom-scroll-listener';\n\nuseBottomScrollListener(callback);\n```\n\n#### On bottom of specific container\n\nUse the hook in any functional component, use the ref given from the hook\nand pass it to the element you want to use as a scroll container\n\nThe callback will be invoked when the user scrolls to the bottom of the container\n\n```jsx\nimport { useBottomScrollListener } from 'react-bottom-scroll-listener';\n\nconst scrollRef = useBottomScrollListener(callback);\n\n\u003cdiv ref={scrollRef}\u003eCallback will be invoked when this container is scrolled to bottom.\u003c/div\u003e;\n```\n\n**Parameters**\n\n```\nuseBottomScrollListener\u003cT extends HTMLElement\u003e(\n  // Required callback that will be invoked when scrolled to bottom\n  onBottom: () =\u003e void,\n  // Options, entirely optional, you can provide one or several to overwrite the defaults\n  options?: {\n    // Offset from bottom of page in pixels. E.g. 300 will trigger onBottom 300px from the bottom of the page\n    offset?: number\n    // Optional debounce in milliseconds, defaults to 200ms\n    debounce?: number\n    // Overwrite the debounceOptions for lodash.debounce, default to { leading: true }\n    debounceOptions?: DebounceOptions\n    // If container is too short, enables a trigger of the callback if that happens, defaults to false\n    triggerOnNoScroll?: boolean\n  },\n); // returns React.MutableRefObject Optionally you can use this to pass to a element to use that as the scroll container\n```\n\n### Component\n\n[Full example](/example/src/ComponentExample.js)\n\n#### On bottom of entire screen\n\nSimply have the BottomScrollListener anywhere in your application and pass it a function as `onBottom`-prop.\n\n```jsx\nimport BottomScrollListener from 'react-bottom-scroll-listener';\n\n\u003cBottomScrollListener onBottom={callback} /\u003e;\n```\n\n#### On bottom of specific container\n\nPass the BottomScrollListener a function inside the JSX_tag, receive the `scrollRef` in this function from the BottomScrollListener\nand pass it to the component you want to listen for a scroll event on.\n\n```jsx\nimport BottomScrollListener from 'react-bottom-scroll-listener';\n\n\u003cBottomScrollListener onBottom={callback}\u003e\n  {(scrollRef) =\u003e \u003cdiv ref={scrollRef}\u003eCallback will be invoked when this container is scrolled to bottom.\u003c/div\u003e}\n\u003c/BottomScrollListener\u003e;\n```\n\n\u003e Those are some weird children, what's going on?\n\nThis pattern is called \"function as a child\". What this allows is that the BottomScrollListener can pass you a `React.RefObject`. This\n`React.RefObject` can then be passed to whatever component you want to be notified when you hit the bottom of. Without this it would be\ndifficult to attach event listeners for scrolling to an arbitrary element.\n\n**Props**\n\n| Property          |           Type           |     Default     | Description                                                                                                                                                                                                                                                                                 |\n| ----------------- | :----------------------: | :-------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| onBottom          |         Function         |      null       | **(required):** callback invoked when bottom is reached                                                                                                                                                                                                                                     |\n| debounce          |          number          |       200       | milliseconds, how much debounce there should be on the callback                                                                                                                                                                                                                             |\n| offset            |          number          |        0        | offset from bottom in pixels. E.g. 300 if it should invoke `onBottom` 300px before the bottom.                                                                                                                                                                                              |\n| debounceOptions   |     DebounceOptions      | {leading: true} | see the lodash.debounce options: see https://lodash.com/docs/4.17.15#debounce                                                                                                                                                                                                               |\n| triggerOnNoScroll |         boolean          |      false      | if container is too short, enables a trigger of the callback if that happens                                                                                                                                                                                                                |\n| children          | React.Node _or_ Function |      null       | Not required, but you can use this to wrap your components. Most useful when you have some conditional rendering. If this is a function, that function will receive a React.RefObject that _needs_ to be passed to a child element. This element will then be used as the scroll container. |\n\n# Migrating from 2.x.x to 3.x.x\n\nThere are no breaking changes except that the required version of React is now 16.8.0. If you are on an\nolder version of React you can either upgrade React, or stay on version 2.x.x. If you already\nare on a newer version of React you don't have to do anything, except maybe try out the new hook implementation. :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarl-run%2Freact-bottom-scroll-listener","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarl-run%2Freact-bottom-scroll-listener","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarl-run%2Freact-bottom-scroll-listener/lists"}