{"id":17002701,"url":"https://github.com/thierryc/react-scrollama-wrapper","last_synced_at":"2025-03-22T16:30:40.620Z","repository":{"id":46212152,"uuid":"423980767","full_name":"thierryc/react-scrollama-wrapper","owner":"thierryc","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-07T11:25:05.000Z","size":1066,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-01T00:56:59.698Z","etag":null,"topics":["scroll","scrollama","scrollytelling"],"latest_commit_sha":null,"homepage":"https://thierryc.github.io/react-scrollama-wrapper/","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/thierryc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2021-11-02T19:55:59.000Z","updated_at":"2024-10-07T11:24:39.000Z","dependencies_parsed_at":"2024-10-28T14:04:32.820Z","dependency_job_id":null,"html_url":"https://github.com/thierryc/react-scrollama-wrapper","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thierryc%2Freact-scrollama-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thierryc%2Freact-scrollama-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thierryc%2Freact-scrollama-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thierryc%2Freact-scrollama-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thierryc","download_url":"https://codeload.github.com/thierryc/react-scrollama-wrapper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244231511,"owners_count":20419962,"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":["scroll","scrollama","scrollytelling"],"created_at":"2024-10-14T04:28:46.146Z","updated_at":"2025-03-22T16:30:40.135Z","avatar_url":"https://github.com/thierryc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-scrollama-wrapper\n\nReact Scrollama Wrapper is a **easy way** to use the great scrollytelling using **React** and IntersectionObserver **Scrollama** JavaScript lib.\n\nThis project is at an early stage of development, so there are some bugs and some features are not implemented yet.\n\nI need help to test it and improve it, please send me a pull request.\n\n## About Scrollama\n\n[Scrollama](https://github.com/russellgoldenberg/scrollama) is a modern \u0026 lightweight JavaScript library for scrollytelling using IntersectionObserver in favor of scroll events.\n\nThank you to [@codenberg](https://twitter.com/@codenberg) for the original scrollama library.\n\nThe @ap.cx/react-scrollama-wrapper package is a wrapper for the scrollama library. I use it to make scrollytelling with React.\n\n# Version\n\nThe version 3.2.x add hook use context useScrollamaContext.\n\nThe version 3.x.x of the @ap.cx/react-scrollama-wrapper package is build over the 3.x.x version of the scrollama library.\n\nThe version 2.x.x of the @ap.cx/react-scrollama-wrapper package is build over the 2.x.x version of the scrollama library.\n\nThe version 2.x.x is not supported anymore.\n\nThe version are not stritly aligned with each other. The only way to know which version of the scrollama library is used is to check the version of the @ap.cx/react-scrollama-wrapper package.\n\n## Installation\n\n```bash\nnpm install @ap.cx/react-scrollama-wrapper\n```\n\n## Usage\n\n```js\nimport React from 'react';\n...\nimport { Scrollama, Step } from \"@ap.cx/react-scrollama-wrapper\"\n\nexport default function Home() {\n  \n\n  const onStepEnter = (step) =\u003e {\n    /* add your logic here */\n  }\n\n  const onStepExit = (step) =\u003e {\n    /* add your logic here */\n  }\n\n  const onStepProgress = (step) =\u003e {\n    /* add your logic here */\n  }\n\n  return (\n    \u003cScrollama\n      progress // remove this line to disable onStepProgress \n      onStepProgress={onStepProgress} \n      onStepEnter={onStepEnter} \n      onStepExit={onStepExit}\n      // degug  // add this line to see the debug offset triger line in your page\n    \u003e\n      \u003cStep\u003e\n        \u003ch1\u003eStep 1\u003c/h1\u003e\n      \u003c/Step\u003e\n      \u003cStep\u003e\n        \u003ch1\u003eStep 2\u003c/h1\u003e\n      \u003c/Step\u003e\n      \u003cStep\u003e\n        \u003ch1\u003eStep 3\u003c/h1\u003e\n      \u003c/Step\u003e\n      \u003cStep\u003e\n        \u003ch1\u003eStep 4\u003c/h1\u003e\n      \u003c/Step\u003e\n    \u003c/Scrollama\u003e\n  )\n}\n\n```\n\nTake a look at the code in the [gh-pages](https://thierryc.github.io/react-scrollama-wrapper/) branch of the @ap.cx/react-scrollama-wrapper repository to see how it works.\nThe gh-pages is build on [Next.js](https://nextjs.org).\n\n## How to style the component?\n\nYou can use className or style or css in js to style the Scrollama and Step component.\n\n```js\n\n\u003cScrollama\n  style={{ width: \"100%\", height: \"100%\" }}\n  className=\"my-custom-class\"\n  ...\n\u003e\n\n```\n\nI use it with [https://stitches.dev](stitches).\n\n```js\n\n... soon\n\n```\n\n#### onStepEnter(callback)\n\nCallback that fires when the top or bottom edge of a step element enters the\noffset threshold.\n\nThe argument of the callback is an object: `{ element: DOMElement, index: number, direction: string }`\n\n`element`: The step element that triggered\n\n`index`: The index of the step of all steps\n\n`direction`: 'up' or 'down'\n\n#### onStepExit(callback)\n\nCallback that fires when the top or bottom edge of a step element exits the\noffset threshold.\n\nThe argument of the callback is an object: `{ element: DOMElement, index: number, direction: string }`\n\n`element`: The step element that triggered\n\n`index`: The index of the step of all steps\n\n`direction`: 'up' or 'down'\n\n#### onStepProgress(callback)\n\nCallback that fires the progress (0 - 1) a step has made through the threshold.\n\nThe argument of the callback is an object: `{ element: DOMElement, index: number, progress: number }`\n\n`element`: The step element that triggered\n\n`index`: The index of the step of all steps\n\n`progress`: The percent of completion of the step (0 - 1)\n\n\nSure! Here's the documentation for adding a component to the Scrollama context using the `useScrollamaContext` hook and passing a React ref created with `React.createRef()`. It also includes the code for removing the component before unmounting:\n\n---\n\n**Adding and Removing a Component from Scrollama Context**\n\nThe Scrollama library provides a convenient way to create scroll-driven interactions in React applications. To add a component to the Scrollama context and remove it before unmounting, you can follow the steps outlined below.\n\n1. Import the necessary dependencies:\n   ```jsx\n   import React, { useEffect, useContext } from 'react';\n   import { useScrollamaContext } from 'scrollama';\n   ```\n\n2. Create a React ref for your component using `React.createRef()`:\n   ```jsx\n   const stepRef = React.createRef();\n   ```\n\n3. Use the `useScrollamaContext` hook to access the Scrollama context:\n   ```jsx\n   const removeStep = useScrollamaContext();\n   ```\n\n4. Add the component to the Scrollama context when the component mounts:\n   ```jsx\n   useEffect(() =\u003e {\n     const remove = removeStep(stepRef);\n     return () =\u003e {\n       remove();\n     };\n   }, []);\n   ```\n\n   In the above code, the `useEffect` hook is used to execute the code when the component mounts. The `removeStep` function returned by the `useScrollamaContext` hook is called with the `stepRef` as an argument. The returned `remove` function is stored in the `remove` variable. Finally, the `remove` function is called when the component is unmounted.\n\n   **Note**: The `[]` as the second argument for `useEffect` ensures that the effect is only run once when the component mounts.\n\n5. The complete code for a component using Scrollama context and removing it before unmounting might look like this:\n   ```jsx\n   import React, { useEffect, useContext } from 'react';\n   import { useScrollamaContext } from 'scrollama';\n\n   const MyComponent = () =\u003e {\n     const stepRef = React.createRef();\n     const removeStep = useScrollamaContext();\n\n     useEffect(() =\u003e {\n       const remove = removeStep(stepRef);\n       return () =\u003e {\n         remove();\n       };\n     }, []);\n\n     // Rest of your component code\n\n     return \u003cdiv ref={stepRef}\u003eYour component content\u003c/div\u003e;\n   };\n\n   export default MyComponent;\n   ```\n\n   In this example, the `stepRef` is assigned to the `ref` prop of the component's root element (`div`). Make sure to replace `'Your component content'` with your actual component content.\n\n   By using this code, your component will be added to the Scrollama context when it mounts, and it will be automatically removed when it unmounts.\n\n---\n\nRemember to install the Scrollama library and any additional dependencies required for your project. Additionally, ensure that you have the correct version of React and Scrollama for compatibility with the `useScrollamaContext` hook. Refer to the official documentation of Scrollama and React for more details and specific usage instructions.\n\n\n\n### Dependencies (3)\n\n- react 17.0.0 || 18.0.0\n- react-dom 17.0.0 || 18.0.0\n- scrollama ^3.0.1\n \n ### A wrapper for Scrollama\n \n This repo is NOT a fork of react-scrollama but a wrapper over the greate original **Scrollama** made and support by [https://github.com/russellgoldenberg](Russell Goldenberg).\n\n ### Alternatives\n\n- [react-scrolly](https://github.com/garfieldduck/react-scrolly)\n- [Scrollama](https://github.com/russellgoldenberg/scrollama)\n- [Waypoints](http://imakewebthings.com/waypoints/)\n- [ScrollMagic](http://scrollmagic.io/)\n- [graph-scroll.js](https://1wheel.github.io/graph-scroll/)\n- [ScrollStory](https://sjwilliams.github.io/scrollstory/)\n- [enter-view](https://github.com/russellgoldenberg/enter-view)\n\n\n## Design scrolly-telling\n\nHere are some references to help you design better scrolly-telling:\n\n- [How To Scroll](https://bost.ocks.org/mike/scroll/) by Mike Bostock\n- [Responsive scrollytelling best practices](https://pudding.cool/process/responsive-scrollytelling/) (The Pudding)\n\n\n## IntersectionObserver polyfill\n\nYou must include the [IntersectionObserver polyfill](https://github.com/w3c/IntersectionObserver) yourself for cross-browser support.\nCheck on [caniuse (intersectionobserver)](https://caniuse.com/#feat=intersectionobserver) to see if you need to include the polyfill.\n\n[IntersectionObserver library polyfills](https://github.com/w3c/IntersectionObserver) is the native IntersectionObserver API in unsupporting browsers. See the API documentation for usage information.\n\n### License\n\nLike the orginal the @ap.cx/react-scrollama-wrapper is licensed under the MIT license\n\nMIT License\n\nCopyright (c) 2021 Thierry Charbonnel\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthierryc%2Freact-scrollama-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthierryc%2Freact-scrollama-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthierryc%2Freact-scrollama-wrapper/lists"}