https://cdn.jsdelivr.net/gh/studio-freight/lenis@0.2.28/README.md [![LENIS](https://assets.studiofreight.com/lenis/header.png)](https://github.com/studio-freight/lenis) [![npm version](https://img.shields.io/badge/dynamic/json?color=blue&label=npm&prefix=v&query=version&suffix=%20&url=https%3A%2F%2Fraw.githubusercontent.com%2Fstudio-freight%2Flenis%2Fmain%2Fpackage.json)](https://www.npmjs.com/package/@studio-freight/lenis) ## Introduction 🚧 Still in WIP, API might change with new releases 🚧 This is our take on smooth scroll, lightweight, hard working, smooth as butter scroll. See [Demo](https://lenis.studiofreight.com/)
## Features - Performant - Lightweight [(~2Kb gzipped)](https://bundlejs.com/?q=%40studio-freight%2Flenis) - Run scroll in main thread - Accessibility (CMD+F page search, keyboard navigation, keep scroll position on page refresh, etc.) - External RAF - SSR proof - Not opinionated - Tree-shakeable - Custom scroll easing/duration
| Feature | [Locomotive-scroll](https://github.com/locomotivemtl/locomotive-scroll) | [GSAP ScrollSmoother](https://greensock.com/scrollsmoother/) | [Lenis](https://github.com/studio-freight/lenis) | | --------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | Native scrollbar | ❌ | ✅ | ✅ | | Native scroll inputs | ❌ | ✅ | ❌ | | Normalize scroll experience | ✅ | ❌ | ✅ | | Accessibility | ❌ | ❌ | ✅ | | CSS Sticky | ❌ | ❌ | ✅ | | IntsersectionObserver | ❌ | ❌ | ✅ | | Open source | ✅ | ❌ | ✅ | | Built-in animation system | ✅ | ✅ | ❌ | | Size (gzip) | [12.33KB](https://bundlejs.com/?q=locomotive-scroll) | [26.08KB](https://bundlejs.com/?q=gsap%2FScrollSmoother&treeshake=%5B%7BScrollSmoother%7D%5D) | [2.13kb](https://bundlejs.com/?q=%40studio-freight%2Flenis) |
## Installing using package manager: ```bash $ npm i @studio-freight/lenis ```
using scripts: ```htmt ```
## Setup Basic setup ```js import Lenis from '@studio-freight/lenis' const lenis = new Lenis({ duration: 1.2, easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)), // https://www.desmos.com/calculator/brs54l4xou direction: 'vertical', // vertical, horizontal gestureDirection: 'vertical', // vertical, horizontal, both smooth: true, mouseMultiplier: 1, smoothTouch: false, touchMultiplier: 2, infinite: false, }) //get scroll value lenis.on('scroll', ({ scroll, limit, velocity, direction, progress }) => { console.log({ scroll, limit, velocity, direction, progress }) }) function raf(time) { lenis.raf(time) requestAnimationFrame(raf) } requestAnimationFrame(raf) ```
Using custom scroll container ```js const lenis = new Lenis({ wrapper: NodeElement, // element which has overflow content: NodeElement, // usually wrapper's direct child }) ```
## Instance settings | Option | Type | Default | Description | | ------------------ | ------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `wrapper` | `NodeElement` | `window` | Default element which has overflow | | `content` | `NodeElement` | `document.documentElement` | `wrapper`'s direct child | | `duration` | `number` | `1.2` | Specifies the duration of the animation | | `easing` | `function` | `(t) => Math.min(1, 1.001 - Math.pow(2, -10 * t))` | Specifies the rate of change of a specific value, our default is custom but you can pick one from [Easings.net](https://easings.net/en) | | `direction` | `string` | `vertical` | `vertical` or `horizontal` scrolling. | | `gestureDirection` | `string` | `vertical` | `vertical`, `horizontal` or `both`. | | `smooth` | `boolean` | `true` | Enable or disable 'smoothness' | | `mouseMultiplier` | `number` | `1` | This value is passed directly to [Virtual Scroll](https://github.com/ayamflow/virtual-scroll) | | `smoothTouch` | `boolean` | `false` | Enable or disable 'smoothness' while scrolling using touch. Note: We have disabled it by default because touch devices native smoothness is impossible to mimic | | `touchMultiplier` | `number` | `string` | This value is passed directly to [Virtual Scroll](https://github.com/ayamflow/virtual-scroll) | | `infinite` | `boolean` | `false` | Enable infinite scrolling! |
## Instance Methods | Method | Description | Arguments | | -------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `raf(time)` | Must be called every frame for internal usage. | | | `scrollTo(target,{offset, duration, easing, immediate})` | Scroll to a target. | `target`: can be `Number`, `NodeElement` or `String` (CSS selector).
`offset` : `Number` equivalent to [scroll-padding-top](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-padding-top).
`duration` : `Number` scroll duration in seconds.
`easing` : `Function`.
`immediate` : ignore duration and easing. | | `on(id,callback({scroll,limit,velocity,direction}))` | `id` can be any of the following [instance events](#instance-events) to listen. | | | `stop()` | To pause the scroll | | | `start()` | To resume the scroll | | | `destroy()` | To destroy the instance and remove all events. | | ## Instance Events | Event | Callback Arguments | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `scroll` | `scroll`: returns scroll position.
`limit`: returns scroll limit.
`velocity`: returns scroll velocity.
`direction`: returns `1` or `-1`. |
## Considerations ### Things to consider if you want to add Lenis to your codebase will be listed here. #### Make sure `scroll-behavior` is set to initial or not set at all (thanks [@thagxt](https://github.com/thagxt)) ```css html { scroll-behavior: initial; } ``` #### Keep html and body elements default sized ([see this issue](https://github.com/studio-freight/lenis/issues/10)) ```css html, body { min-height: 100%; height: auto; } ``` #### Use `data-lenis-prevent` attribute on nested scroll elements. In addition, we advice you to add `overscroll-behavior: contain` on this element. ```html
scroll content
``` #### Manually use `lenis.scrollTo('#anchor')` on anchor link click ([see this issue](https://github.com/studio-freight/lenis/issues/19)) ```html scroll to anchor ```
## Limitations - no support of CSS scroll-snap - can only run 60fps maximum on Safari ([source](https://bugs.webkit.org/show_bug.cgi?id=173434))
## Tutorials - [Scroll Animation Ideas for Image Grids](https://tympanus.net/Development/ScrollAnimationsGrid/) by [Codrops](https://tympanus.net/codrops) - [How to Animate SVG Shapes on Scroll](https://tympanus.net/codrops/2022/06/08/how-to-animate-svg-shapes-on-scroll) by [Codrops](https://tympanus.net/codrops) - [The BEST smooth scrolling library for your Webflow website! (Lenis)](https://www.youtube.com/watch?v=VtCqTLRRMII) by [Diego Toda de Oliveira](https://www.diegoliv.works/) - [Easy smooth scroll in @Webflow with Lenis + GSAP ScrollTrigger tutorial](https://www.youtube.com/watch?v=gRKuzQTXq74) by [También Studio](https://www.tambien.studio/)
## Plugins - [Loconative-scroll](https://github.com/quentinhocde/loconative-scroll#how-to-switch-from-locomotive-scroll-to-loconative-scroll) by [Quentin Hocde](https://twitter.com/QuentinHocde)
## Lenis in use - [Wyre](https://www.sendwyre.com/) by [Studio Freight](https://www.studiofreight.com/) - [Lunchbox](https://lunchbox.io/) by [Studio Freight](https://www.studiofreight.com/) - [Easol](https://easol.com/) by [Studio Freight](https://www.studiofreight.com/) - [Repeat](https://getrepeat.io/) by [Studio Freight](https://www.studiofreight.com/) - [Dragonfly](https://dragonfly.xyz/) by [Studio Freight](https://www.studiofreight.com/) - [Yuga Labs](https://yuga.com/) by [Antinomy Studio](https://antinomy.studio/) - [Quentin Hocde's Portfolio](https://quentinhocde.com) by [Quentin Hocde](https://twitter.com/QuentinHocde) - [Houses Of](https://housesof.world) by [Félix P.](https://flayks.com/) & [Shelby Kay](https://shelbykay.dev/) - [Shelby Kay's Portfolio](https://shelbykay.dev) by [Shelby Kay](https://shelbykay.dev/) - [Heights Agency Portfolio](https://www.heights.agency/) by [Francesco Michelini](https://www.francescomichelini.com/) - [Goodship](https://goodship.io) by [Studio Freight](https://www.studiofreight.com/) - [Flayks' Portfolio](https://flayks.com) by [Félix P.](https://flayks.com/) & [Shelby Kay](https://shelbykay.dev/)
## Authors This set of hooks is curated and maintained by the Studio Freight Darkroom team: - Clement Roche ([@clementroche\_](https://twitter.com/clementroche_)) – [Studio Freight](https://studiofreight.com) - Guido Fier ([@uido15](https://twitter.com/uido15)) – [Studio Freight](https://studiofreight.com) - Leandro Soengas ([@lsoengas](https://twitter.com/lsoengas)) - [Studio Freight](https://studiofreight.com) - Franco Arza ([@arzafran](https://twitter.com/arzafran)) - [Studio Freight](https://studiofreight.com)
## License [The MIT License.](https://opensource.org/licenses/MIT) https://cdn.jsdelivr.net/gh/studio-freight/lenis@0.2.28/package.json { "name": "@studio-freight/lenis", "version": "0.2.28", "description": "Lenis is a smooth scroll library to normalize the scrolling experience across devices", "files": [ "dist" ], "sideEffects": false, "source": "src/lenis.js", "main": "dist/lenis.js", "umd:main": "dist/lenis.umd.js", "module": "dist/lenis.mjs", "types": "dist/lenis.d.ts", "exports": { "require": "./dist/lenis.js", "default": "./dist/lenis.modern.mjs" }, "devDependencies": { "@size-limit/preset-small-lib": "^8.1.0", "husky": "^8.0.2", "lint-staged": "^13.0.3", "microbundle": "^0.15.1", "path": "^0.12.7", "prettier": "^2.8.0", "rimraf": "^3.0.2", "size-limit": "^8.1.0", "stats.js": "^0.17.0", "typescript": "^4.9.3", "vite": "^3.2.4" }, "dependencies": { "tiny-emitter": "^2.1.0", "virtual-scroll": "^2.2.1" }, "author": "studio-freight", "repository": { "type": "git", "url": "git+https://github.com/studio-freight/lenis.git" }, "scripts": { "dev": "microbundle watch -i src/lenis.js --format umd --compress --no-sourcemap --no-pkg-main --external none --output ./bundled --name 'Lenis' & npm run dev:website", "dev:website": "npm run dev:website --prefix ./website", "size": "size-limit", "clean": "rimraf dist && rimraf bundled", "build": "npm run clean && npm run build:light && npm run build:bundle && npm run build:types", "build:types": "tsc --allowJs -d --emitDeclarationOnly --declarationDir dist --removeComments ./src/lenis.js ./src/maths.js", "build:light": "microbundle", "build:bundle": "microbundle build -i src/lenis.js --format umd --compress --no-sourcemap --no-pkg-main --external none --output ./bundled --name Lenis", "build:website": "vite build", "prebuild": "npm run clean", "preversion": "npm run build", "postversion": "git push --follow-tags", "prepublishOnly": "npm run build", "prepare": "husky install" }, "bugs": { "url": "https://github.com/studio-freight/lenis/issues" }, "homepage": "https://github.com/studio-freight/lenis#readme", "keywords": [ "smooth", "scroll" ], "size-limit": [ { "limit": "4.5 kB", "path": "dist/lenis.js" }, { "limit": "4.5 kB", "path": "dist/lenis.mjs" }, { "limit": "4.5 kB", "path": "dist/lenis.modern.mjs" }, { "limit": "4.5 kB", "path": "dist/lenis.umd.js" } ], "lint-staged": { "*.js": "eslint --cache --fix", "*.{js,css,scss,md}": "prettier --write" } } https://cdn.jsdelivr.net/npm/imagesloaded@5.0.0/LICENSE.md Copyright (c) 2011-2022 [David DeSandro](https://desandro.com) and [contributors](https://github.com/desandro/imagesloaded/graphs/contributors) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Standard MIT permission and disclaimer for the original Lenis 0.2.28 MIT declaration. Original authors are retained in its README above. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. GSAP standard license snapshot Source: https://gsap.com/community/standard-license/ Retrieved: 2026-09-22T04:22:49.089Z Original distribution copyright and version headers remain in the runtime code. Standard "No Charge" GSAP License I. DEFINITIONS “GSAP License” means the terms and conditions of this GSAP Software License Agreement. "GSAP Products" means any Software made available at gsap.com (https://gsap.com) or any successor sites, including but not limited to the GSAP animation library and related plugins, tools, or extensions. "Permitted Uses" means the implementation and/or use of GSAP Products on any website, web application, or digital interface by any person or entity (which may include, for clarity, those of companies that compete with Webflow in other areas of business). "Prohibited Uses" means any implementation and/or use of GSAP Products in tools that allow users to build visual animations without code that encourages, induces, or materially assists in creating a solution that competes with Webflow’s visual animation building capabilities. "Competitive Products" means any software, tool, or service that enables users to create, edit, or manage animations through a visual interface or builder similar to Webflow (https://webflow.com). II. GRANT OF LICENSE Subject to the terms and conditions of this GSAP License, Webflow grants you a non-exclusive, worldwide license to use, reproduce, display, and implement GSAP Products solely for Permitted Uses. III. RESTRICTIONS You may not: Use any GSAP Products for any Prohibited Uses without prior written consent; Reverse engineer any GSAP Products for the purpose of creating Competitive Products; Remove or alter any proprietary notices or branding from GSAP Products. IV. OWNERSHIP AND INTELLECTUAL PROPERTY All intellectual property rights in GSAP Products, including but not limited to copyright, patents, trademarks, and trade secrets, remain the exclusive property of Webflow. This GSAP License does not transfer any ownership rights in GSAP Products to you. V. TERMINATION Webflow may terminate this GSAP License and revoke your access in its discretion if you fail to comply with any of these terms and conditions. Upon termination, you must cease all use of GSAP Products and destroy all copies in your possession. VI. MISCELLANEOUS PROVISIONS General: This GSAP License is incorporated into and subject to Webflow’s Terms of Service available here (https://webflow.com/legal/terms) ("Terms of Service"). In the event of any conflict or inconsistency between this GSAP License and the Terms of Service, the terms of this GSAP License shall govern in relation to your use of any GSAP Products. Amendments: Webflow reserves the right to update or modify this GSAP License at any time by posting the revised terms on this website, provided that any such updates or modifications shall not result in any material degradation to the security, integrity, or functionality of any GSAP Products. You understand and agree that your continued use of any GSAP Products after such revisions to this GSAP License constitutes your acceptance of this GSAP License as revised. If you do not accept the revised GSAP License, you are prohibited from using versions of the GSAP Products released after the effective date of the revised GSAP License (as well as any updates made to previous versions). Notwithstanding, you may continue using previous versions of GSAP Products under the applicable terms licensed to you prior to the effective date of the revised GSAP License (for clarity, excluding any updates made thereto). No Waiver: Failure of Webflow to enforce any provision of this GSAP License shall not constitute a waiver of future enforcement of that or any other provision. FAQ Is it acceptable for AI tools like ChatGPT, Cursor, Lovable, Webstudio, etc. to generate GSAP code? Absolutely! AI-generated code is not a "Prohibited Use". What if a WordPress plugin or theme or other niche tool allows users to create GSAP-driven effects through a visual interface? Is that prohibited? We want to encourage developers to build on top of GSAP, including visual tools that don't directly compete with Webflow's rich animation-building capabilities. If you are not sure if your product might be considered a "Prohibited Use", feel free to contact us (https://gsap.com/contact) so we can talk through it! Can I really use GSAP in commercial projects without paying anything? Yes, really! Commercial usage is covered under the standard license. All of GSAP including the plugins that were formerly "members-only" like SplitText (https://gsap.com/docs/v3/Plugins/SplitText/) and MorphSVG (https://gsap.com/docs/v3/Plugins/MorphSVGPlugin) can be used in commercial projects at no charge. Enjoy! 💚 Effective date: April 30, 2025 Last modified date: May 30, 2025 Copyright (©) 2025, Webflow