{"id":13632145,"url":"https://github.com/basementstudio/scrollytelling","last_synced_at":"2025-05-16T06:07:27.078Z","repository":{"id":153883457,"uuid":"625569080","full_name":"basementstudio/scrollytelling","owner":"basementstudio","description":"A library for creating Scrollytelling animations, powered by React \u0026 GSAP.","archived":false,"fork":false,"pushed_at":"2024-02-22T00:40:25.000Z","size":73874,"stargazers_count":1219,"open_issues_count":10,"forks_count":40,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-08T16:06:16.264Z","etag":null,"topics":["animations","basement","gsap","library","react","scrollytelling"],"latest_commit_sha":null,"homepage":"http://scrollytelling.basement.studio","language":"TypeScript","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/basementstudio.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":"2023-04-09T14:19:34.000Z","updated_at":"2025-04-08T07:36:23.000Z","dependencies_parsed_at":"2024-01-15T19:44:47.084Z","dependency_job_id":"aa753218-5feb-40cd-80d0-f5b9a1a49808","html_url":"https://github.com/basementstudio/scrollytelling","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basementstudio%2Fscrollytelling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basementstudio%2Fscrollytelling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basementstudio%2Fscrollytelling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basementstudio%2Fscrollytelling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basementstudio","download_url":"https://codeload.github.com/basementstudio/scrollytelling/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478190,"owners_count":22077676,"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":["animations","basement","gsap","library","react","scrollytelling"],"created_at":"2024-08-01T22:02:53.333Z","updated_at":"2025-05-16T06:07:22.069Z","avatar_url":"https://github.com/basementstudio.png","language":"TypeScript","readme":"# BSMNT Scrollytelling\n\nBSMNT Scrollytelling is a library for creating Scrollytelling animations. It's powered by GSAP ScrollTrigger, but abstracts away some things to make it work better with React.\n\n![Frame 7](https://user-images.githubusercontent.com/40034115/233121992-12eb2448-4f62-4cba-b9a3-c0d3e9233aa7.jpg)\n\n---\n\n### 👇 New documentation here! 👇\n\n- 💡 [Core Concepts](/docs/core-concepts.md)\n- 📕 [API Reference](/docs/api.md)\n\n---\n\n## Installation\n\nTo get started, we'll need the `@bsmnt/scrollytelling` package, as well as the required peer dependency: [GSAP](https://greensock.com/docs/).\n\n```zsh\nyarn add @bsmnt/scrollytelling gsap\n```\n\n## Why\n\nAt [basement](https://basement.studio/), we've built a bunch of websites that use scroll animations. Over the years, we faced some issues that required solutions that we copy-pased throughout different project. We decided to build a library to share how we build these with the world.\n\n**Challenges we faced**\n\n- Needed a deep understanding of how GSAP works with ScrollTrigger.\n- Needed to be careful about running animations inside `useEffect` and then cleaning them up.\n- Couldn’t think of scroll animations in terms of a `start` and an `end`, so it was hard to fire up animations at the exact scroll progress we needed to.\n\n## What\n\nWe aimed at componentizing a way of building scroll animations that could:\n\n- ✅ Provide sensible defaults for scroll animations, such as `scrub: true`, and `ease: 'linear'`.\n- ✅ Take care of component mounting and unmounting.\n- ✅ Create animations with absolute positioning defined by a `start` and an `end`, instead of a time-based `duration`.\n\nAs an added benefit, going \"component-based\" allowed us to:\n\n- ✅ Improve compatibility with React Server Components: our components definitely `'use client'`, but not necessarily the parents or children of our components.\n- ✅ Compose animations at every level of the tree, as it all works with React Context.\n\nA simple example of how this works:\n\n![117 (1)](https://user-images.githubusercontent.com/40034115/233122199-a201e5a0-20d0-4538-a681-a7e9d6f539bb.png)\n\n## Exports\n\n- `Root`: Creates timeline and scrollTrigger, provides React Context.\n- `Animation`: Appends an animation to the timeline. Receives a `tween` prop that will control how the animation behaves.\n- `Waypoint`: Runs a callback or tween at a specific point in the timeline. Can also receive a `label` prop, that will create a GSAP label at that position.\n- `RegisterGsapPlugins`: Registers custom GSAP plugins, if you need them for a specific use case.\n- `Parallax`: Helper to create a simple parallax.\n- `ImageSequenceCanvas`: Helper to create a simple image sequence animation.\n- `useScrollytelling`: Context consumer. Returns the `timeline`.\n- `useScrollToLabel`: Scrolls to the label name you pass. Labels can be added with the `Waypoint` component.\n\n## Demo\n\nWe did a small demo to showcase this library in action. This is the best place to see how the library works in a real world scenario. Check it out:\n\n- Site URL: [https://scrollytelling.basement.studio/](https://scrollytelling.basement.studio/)\n- Code: [https://github.com/basementstudio/scrollytelling/blob/main/website/README.md](https://github.com/basementstudio/scrollytelling/blob/main/website/README.md)\n\n## Examples\n\n- Simple tweening: [https://stackblitz.com/edit/react-ts-8rqm8k?file=App.tsx](https://stackblitz.com/edit/react-ts-8rqm8k?file=App.tsx)\n- With Lenis Smooth Scroll: [https://stackblitz.com/edit/react-ts-uuwfed?file=App.tsx](https://stackblitz.com/edit/react-ts-uuwfed?file=App.tsx)\n- Layered pinning: [https://stackblitz.com/edit/react-ts-4dtlww?file=App.tsx](https://stackblitz.com/edit/react-ts-4dtlww?file=App.tsx)\n- Three.js Tube: [https://codesandbox.io/s/978cns?file=/src/App.js](https://codesandbox.io/s/978cns?file=/src/App.js)\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cb\u003e\"My simple animation is not doing anything on scroll\"\u003c/b\u003e\n\u003c/summary\u003e\n\nPlease check your `start` and `end` values for your `Root` component. A typical issue comes when:\n\n1. your animation _\"starts when the start of the scroller hits the start of the viewport\"_,\n2. your animation _\"ends when the bottom of the scroller hits the bottom of the viewport\"_,\n3. the element your `Root` wraps around is only `100vh` tall, so the animation's duration is 0.\n\nTo fix this, either add more height to the element your `Root` wraps, or tweak the `end` value to be something like `bottom start`, which would mean \"when the bottom of the scroller hits the start of the viewport\".\n\n\u003c/details\u003e\n\n---\n\nGSAP files are subject to GreenSock's standard license which can be found at [https://greensock.com/standard-license/](https://greensock.com/standard-license/)\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasementstudio%2Fscrollytelling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasementstudio%2Fscrollytelling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasementstudio%2Fscrollytelling/lists"}