├── .gitattributes ├── .github └── FUNDING.yml ├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── bower.json ├── build.js ├── demos ├── callback.html └── default.html ├── dist └── basicScroll.min.js ├── package.json └── src └── scripts └── main.js /.gitattributes: -------------------------------------------------------------------------------- 1 | dist/**/* binary -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: electerious 2 | custom: ['https://paypal.me/electerious', 'https://www.buymeacoffee.com/electerious'] -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | yarn.lock 3 | package-lock.json -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). 6 | 7 | ## [3.0.4] - 2021-01-17 8 | 9 | ### Changed 10 | 11 | - Updated dependencies 12 | 13 | ## [3.0.3] - 2020-03-20 14 | 15 | ### Changed 16 | 17 | - Updated dependencies 18 | - Updated documentation 19 | 20 | ## [3.0.2] - 2019-02-23 21 | 22 | ### Changed 23 | 24 | - Replace `gulp` and `basicTasks` with custom build process 25 | 26 | ## [3.0.1] - 2018-12-20 27 | 28 | ### Added 29 | 30 | - Support SSR by checking if `window` exists (#32) 31 | 32 | ## [3.0.0] - 2018-10-03 33 | 34 | ### Added 35 | 36 | - Reduced the size of the minified version by almost 50% 37 | - `Object.assign` must be supported by the browser 38 | 39 | ### Fixed 40 | 41 | - "Missing property `from`" error (#21) 42 | 43 | ## [2.1.1] - 2018-04-01 44 | 45 | ### Changed 46 | 47 | - Precise property rounding to avoid choppy animations (#16) 48 | 49 | ## [2.1.0] - 2018-03-09 50 | 51 | ### Added 52 | 53 | - `direct` option can be used to apply properties to another element than `elem` (#11) 54 | - More demos 55 | 56 | ## [2.0.0] - 2018-02-25 57 | 58 | ### Added 59 | 60 | - [Track window size changes](README.md#track-window-size-changes) and recalculate and update instances when the size changes (#7) 61 | - `track` option to disable [window size tracking](README.md#track-window-size-changes) for each instance individually (#7) 62 | 63 | ### Changed 64 | 65 | - The `props` callback parameter is now nicely formatted 66 | - The `update` method returns a nicely formatted object of props 67 | - [Direct mode](README.md#data) must now be defined globally per instance instead of setting it on each prop individually 68 | 69 | ## [1.3.0] - 2018-02-24 70 | 71 | ### Added 72 | 73 | - Callback demo 74 | - Destroy method (#6) 75 | 76 | ## [1.2.0] - 2018-01-18 77 | 78 | ### Added 79 | 80 | - `inside` and `outside` callbacks now receive the calculated properties 81 | 82 | ## [1.1.5] - 2017-12-17 83 | 84 | ### Changed 85 | 86 | - Syntax of JS files 87 | 88 | ## [1.1.4] - 2017-09-01 89 | 90 | ### Changed 91 | 92 | - Switched from `deepcopy` to `lodash.clonedeep` 93 | 94 | ## [1.1.3] - 2017-08-08 95 | 96 | ### Added 97 | 98 | - Added a changelog 99 | 100 | ### Changed 101 | 102 | - Ignore `yarn.lock` and `package-lock.json` files -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) Tobias Reich 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in 13 | all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | THE SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # basicScroll 2 | 3 | [![Donate via PayPal](https://img.shields.io/badge/paypal-donate-009cde.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=CYKBESW577YWE) 4 | 5 | Standalone parallax scrolling for mobile and desktop with CSS variables. 6 | 7 | basicScroll allows you to change CSS variables depending on the scroll position. Use the variables directly in your CSS to animate whatever you want. Highly inspired by [skrollr](https://github.com/Prinzhorn/skrollr) and [Reactive Animations with CSS Variables](http://slides.com/davidkhourshid/reactanim#/). 8 | 9 | ## Contents 10 | 11 | - [Demos](#demos) 12 | - [Tutorials](#tutorials) 13 | - [Features](#features) 14 | - [Requirements](#requirements) 15 | - [Setup](#setup) 16 | - [API](#api) 17 | - [Instance API](#instance-api) 18 | - [Data](#data) 19 | - [Related](#related) 20 | - [Tips](#tips) 21 | 22 | ## Demos 23 | 24 | | Name | Description | Link | Author | 25 | |:-----------|:------------|:------------|:------------| 26 | | Default | Includes most features | [Try it on CodePen](http://codepen.io/electerious/pen/QGNxxx) | 27 | | Callback | Animate properties in JS via callbacks | [Try it on CodePen](https://codepen.io/electerious/pen/goZRBv) | 28 | | Parallax scene | A composition of multiple, moving layers | [Try it on CodePen](http://codepen.io/electerious/pen/gLLozQ) | [@electerious](https://twitter.com/electerious) | 29 | | Rolling eyes | Custom element to track scrolling | [Try it on CodePen](https://codepen.io/electerious/pen/MZJZxm) | [@electerious](https://twitter.com/electerious) | 30 | | Headline explosion | Animated letters | [Try it on CodePen](https://codepen.io/electerious/pen/EQzxxJ) | [@electerious](https://twitter.com/electerious) | 31 | | Scroll and morph | Morph text using CSS clip-path | [Try it on CodePen](https://codepen.io/ainalem/pen/jZzxrP) | [@mikaelainalem](https://twitter.com/mikaelainalem) | 32 | | Parallax with JS | Several examples and a debug mode | [Try it on CodePen](https://codepen.io/animaticss/pen/rNBJwmq) | [AnimatiCSS](https://www.youtube.com/channel/UC73Tk5wfEBh67Vm7gM_zaAw) | 33 | 34 | ## Tutorials 35 | 36 | | Name | Link | 37 | |:-----------|:------------| 38 | | 📃 Parallax scrolling with JS controlled CSS variables | [Read it on Medium](https://medium.com/@electerious/parallax-scrolling-with-js-controlled-css-variables-63cfe96820c7) | 39 | | 🎬 Apple-like scroll animations | [Watch it on YouTube](https://www.youtube.com/watch?v=hPd1srSWDU4) | 40 | | 🎬 Parallax effect tutorial (🇪🇸) | [Watch it on YouTube](https://www.youtube.com/watch?v=QeRg4t3I2zc) | 41 | 42 | ## Features 43 | 44 | - Framework independent 45 | - Insane performance 46 | - Support for mobile and desktop 47 | - CommonJS and AMD support 48 | - Simple JS API 49 | 50 | ## Requirements 51 | 52 | basicScroll depends on the following browser features and APIs: 53 | 54 | - [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) 55 | - [Object.assign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) 56 | - [window.requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) 57 | 58 | Some of these APIs are capable of being polyfilled in older browsers. Check the linked resources above to determine if you must polyfill to achieve your desired level of browser support. 59 | 60 | ## Setup 61 | 62 | We recommend installing basicScroll using [npm](https://npmjs.com) or [yarn](https://yarnpkg.com). 63 | 64 | ```sh 65 | npm install basicscroll 66 | ``` 67 | 68 | ```sh 69 | yarn add basicscroll 70 | ``` 71 | 72 | Include the JS file at the end of your `body` tag… 73 | 74 | ```html 75 | 76 | ``` 77 | 78 | …or skip the JS file and use basicScroll as a module: 79 | 80 | ```js 81 | const basicScroll = require('basicscroll') 82 | ``` 83 | 84 | ```js 85 | import * as basicScroll from 'basicscroll' 86 | ``` 87 | 88 | ## Usage 89 | 90 | This demo shows how to to change the opacity of an element when the user scrolls. The element starts to fade as soon as the top of the element reaches the bottom of the viewport. A opacity of `.99` is reached when the middle of the element is in the middle of the viewport. 91 | 92 | Tip: Animating from `.01` to `.99` avoids the repaints that normally occur when the element changes from fully transparent to translucent and from translucent to fully visible. 93 | 94 | ```js 95 | const instance = basicScroll.create({ 96 | elem: document.querySelector('.element'), 97 | from: 'top-bottom', 98 | to: 'middle-middle', 99 | props: { 100 | '--opacity': { 101 | from: .01, 102 | to: .99 103 | } 104 | } 105 | }) 106 | 107 | instance.start() 108 | ``` 109 | 110 | ```css 111 | .element { 112 | /* 113 | * Use the same CSS variable as specified in our instance. 114 | */ 115 | opacity: var(--opacity); 116 | /* 117 | * The will-change CSS property provides a way for authors to hint browsers about the kind of changes 118 | * to be expected on an element, so that the browser can setup appropriate optimizations ahead of time 119 | * before the element is actually changed. 120 | */ 121 | will-change: opacity; 122 | } 123 | ``` 124 | 125 | ## API 126 | 127 | ### .create(html, opts) 128 | 129 | Creates a new basicScroll instance. 130 | 131 | Be sure to assign your instance to a variable. Using your instance, you can… 132 | 133 | * …start and stop the animation. 134 | * …check if the instance is active. 135 | * …get the current props. 136 | * …recalculate the props when the window size changes. 137 | 138 | Examples: 139 | 140 | ```js 141 | const instance = basicScroll.create({ 142 | from: '0', 143 | to: '100px', 144 | props: { 145 | '--opacity': { 146 | from: 0, 147 | to: 1 148 | } 149 | } 150 | }) 151 | ``` 152 | 153 | ```js 154 | const instance = basicScroll.create({ 155 | elem: document.querySelector('.element'), 156 | from: 'top-bottom', 157 | to: 'bottom-top', 158 | props: { 159 | '--translateY': { 160 | from: '0', 161 | to: '100%', 162 | timing: 'elasticOut' 163 | } 164 | } 165 | }) 166 | ``` 167 | 168 | ```js 169 | const instance = basicScroll.create({ 170 | elem: document.querySelector('.element'), 171 | from: 'top-middle', 172 | to: 'bottom-middle', 173 | inside: (instance, percentage, props) => { 174 | console.log('viewport is inside from and to') 175 | }, 176 | outside: (instance, percentage, props) => { 177 | console.log('viewport is outside from and to') 178 | } 179 | }) 180 | ``` 181 | 182 | Parameters: 183 | 184 | - `data` `{Object}` An object of [data](#data). 185 | 186 | Returns: 187 | 188 | - `{Object}` The created instance. 189 | 190 | ## Instance API 191 | 192 | Each basicScroll instance has a handful of handy functions. Below are all of them along with a short description. 193 | 194 | ### .start() 195 | 196 | Starts to animate the instance. basicScroll will track the scroll position and adjust the [props](#props) of the instance accordingly. An update will be performed only when the scroll position has changed. 197 | 198 | Example: 199 | 200 | ```js 201 | instance.start() 202 | ``` 203 | 204 | ### .stop() 205 | 206 | Stops to animate the instance. All [props](#props) of the instance will keep their last value. 207 | 208 | Example: 209 | 210 | ```js 211 | instance.stop() 212 | ``` 213 | 214 | ### .destroy() 215 | 216 | Destroys the instance. Should be called when the instance is no longer needed. All [props](#props) of the instance will keep their last value. 217 | 218 | Example: 219 | 220 | ```js 221 | instance.destroy() 222 | ``` 223 | 224 | ### .update() 225 | 226 | Triggers an update of an instance, even when the instance is currently stopped. 227 | 228 | Example: 229 | 230 | ```js 231 | const props = instance.update() 232 | ``` 233 | 234 | Returns: 235 | 236 | - `{Object}` Applied props. 237 | 238 | ### .calculate() 239 | 240 | Converts the [start and stop position](#start-and-stop-position) of the instance to absolute values. basicScroll relies on those values to start and stop the animation at the right position. It runs the calculation once during the instance creation. `.calculate()` should be called when elements have altered their position or when the size of the site/viewport has changed. 241 | 242 | Example: 243 | 244 | ```js 245 | instance.calculate() 246 | ``` 247 | 248 | ### .isActive() 249 | 250 | Returns `true` when the instance is started and `false` when the instance is stopped. 251 | 252 | Example: 253 | 254 | ```js 255 | instance.isActive() 256 | ``` 257 | 258 | Returns: 259 | 260 | - `{Boolean}` 261 | 262 | ### .getData() 263 | 264 | Returns calculated data. More or less a parsed version of the [data](#data) used for the instance creation. The data might change when calling the [calculate](#calculate) function. 265 | 266 | Example: 267 | 268 | ```js 269 | instance.getData() 270 | ``` 271 | 272 | Returns: 273 | 274 | - `{Object}` Parsed [data](#data). 275 | 276 | ## Data 277 | 278 | The data object can include the following properties: 279 | 280 | ```js 281 | { 282 | /* 283 | * DOM element/node. 284 | */ 285 | elem: null, 286 | /* 287 | * Start and stop position. 288 | */ 289 | from: null, 290 | to: null, 291 | /* 292 | * Direct mode. 293 | */ 294 | direct: false, 295 | /* 296 | * Track window size changes. 297 | */ 298 | track: true, 299 | /* 300 | * Callback functions. 301 | */ 302 | inside: (instance, percentage, props) => {}, 303 | outside: (instance, percentage, props) => {}, 304 | /* 305 | * Props. 306 | */ 307 | props: { 308 | /* 309 | * Property name / CSS Custom Properties. 310 | */ 311 | '--name': { 312 | /* 313 | * Start and end values. 314 | */ 315 | from: null, 316 | to: null, 317 | /* 318 | * Animation timing. 319 | */ 320 | timing: 'ease' 321 | } 322 | } 323 | } 324 | ``` 325 | 326 | ### DOM element/node 327 | 328 | Type: `Node` Default: `null` Optional: `true` 329 | 330 | A DOM element/node. 331 | 332 | The position and size of the element will be used to convert the [start and stop position](#start-and-stop-position) to absolute values. How else is basicScroll supposed to know when to start and stop an animation with relative values? 333 | 334 | You can skip the property when using absolute values. 335 | 336 | Example: 337 | 338 | ```js 339 | { 340 | elem: document.querySelector('.element') 341 | /* ... */ 342 | } 343 | ``` 344 | 345 | ### Start and stop position 346 | 347 | Type: `Integer|String` Default: `null` Optional: `false` 348 | 349 | basicScroll starts to animate the [props](#props) when the scroll position is above `from` and below `to`. Absolute and relative values are allowed. 350 | 351 | Relative values require a [DOM element/node](#dom-elementnode). The first part of the value describes the element position, the last part describes the viewport position: `-`. `middle-bottom` in `from` specifies that the animation starts when the middle of the element reaches the bottom of the viewport. 352 | 353 | Known relative values: `top-top`, `top-middle`, `top-bottom`, `middle-top`, `middle-middle`, `middle-bottom`, `bottom-top`, `bottom-middle`, `bottom-bottom` 354 | 355 | It's possible to track a custom anchor when you want to animate for [a specific viewport height](https://github.com/electerious/basicScroll/issues/26#issuecomment-449130809) or when you need to [start and end with an offset](https://github.com/electerious/basicScroll/issues/17#issuecomment-449134650). 356 | 357 | Examples: 358 | 359 | ```js 360 | { 361 | /* ... */ 362 | from: '0px', 363 | to: '100px', 364 | /* ... */ 365 | } 366 | ``` 367 | 368 | ```js 369 | { 370 | /* ... */ 371 | from: 0, 372 | to: 360, 373 | /* ... */ 374 | } 375 | ``` 376 | 377 | ```js 378 | { 379 | /* ... */ 380 | from: 'top-middle', 381 | to: 'bottom-middle', 382 | /* ... */ 383 | } 384 | ``` 385 | 386 | ### Direct mode 387 | 388 | Type: `Boolean|Node` Default: `false` Optional: `true` 389 | 390 | basicScroll applies all [props](#props) globally by default. This way you can use variables everywhere in your CSS, even when the instance tracks just one element. Set `direct` to `true` or to a DOM element/node to apply all [props](#props) directly to the [DOM element/node](#dom-elementnode) or to the DOM element/node you have specified. This also allows you to animate CSS properties, not just CSS variables. 391 | 392 | - `false`: Apply props globally (default) 393 | - `true`: Apply props to the [DOM element/node](#dom-elementnode) 394 | - `Node`: Apply props to a DOM element/node of your choice 395 | 396 | Examples: 397 | 398 | ```html 399 | 400 | 401 |
402 |
403 | 404 | ``` 405 | 406 | ```html 407 | 408 | 409 |
410 |
411 | 412 | ``` 413 | 414 | ```html 415 | 416 | 417 |
418 |
419 | 420 | ``` 421 | 422 | ### Track window size changes 423 | 424 | Type: `Boolean` Default: `true` Optional: `true` 425 | 426 | basicScroll automatically recalculates and updates instances when the size of the window changes. You can disable the tracking for each instance individually when you want to take care of it by yourself. 427 | 428 | Note: basicScroll only tracks the window size. You still must recalculate and update your instances manually when you modify your site. Each modification that changes the layout of the page should trigger such an update in your code. 429 | 430 | Example: 431 | 432 | ```js 433 | const instance = basicScroll.create({ 434 | elem: document.querySelector('.element'), 435 | from: 'top-bottom', 436 | to: 'bottom-top', 437 | track: false, 438 | props: { 439 | '--opacity': { 440 | from: 0, 441 | to: 1 442 | } 443 | } 444 | }) 445 | 446 | // Recalculate and update your instance manually when the tracking is disabled. 447 | // Debounce this function in production to avoid unnecessary calculations. 448 | window.onresize = function() { 449 | 450 | instance.calculate() 451 | instance.update() 452 | 453 | } 454 | ``` 455 | 456 | ### Callback functions 457 | 458 | Type: `Function` Default: `() => {}` Optional: `true` 459 | 460 | - The `inside` callback executes when the user scrolls and the viewport is within the given [start and stop position](#start-and-stop-position). 461 | - The `outside` callback executes when the user scrolls and the viewport is outside the given [start and stop position](#start-and-stop-position). 462 | 463 | Both callbacks receive the current instance, a percentage and the calculated properties: 464 | 465 | - `< 0%` percent = Scroll position is below `from` 466 | - `= 0%` percent = Scroll position is `from` 467 | - `= 100%` percent = Scroll position is `to` 468 | - `> 100%` percent = Scroll position is above `from` 469 | 470 | Example: 471 | 472 | ```js 473 | { 474 | /* ... */ 475 | inside: (instance, percentage, props) => {}, 476 | outside: (instance, percentage, props) => {}, 477 | /* ... */ 478 | } 479 | ``` 480 | 481 | ### Props 482 | 483 | Type: `Object` Default: `{}` Optional: `true` 484 | 485 | Values to animate when the scroll position changes. 486 | 487 | Each prop of the object represents a CSS property or CSS Custom Property (CSS variables). Custom CSS properties always start with two dashes. A prop with the name `--name` is accessible with `var(--name)` in CSS. 488 | 489 | More about [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables). 490 | 491 | Example: 492 | 493 | ```js 494 | { 495 | /* ... */ 496 | props: { 497 | '--one-variable': { /* ... */ }, 498 | '--another-variable': { /* ... */ } 499 | } 500 | } 501 | ``` 502 | 503 | ### Start and end values 504 | 505 | Type: `Integer|String` Default: `null` Optional: `false` 506 | 507 | Works with all kinds of units. basicScroll uses the unit of `to` when `from` has no unit. 508 | 509 | Examples: 510 | 511 | ```js 512 | '--name': { 513 | /* ... */ 514 | from: '0', 515 | to: '100px', 516 | /* ... */ 517 | } 518 | ``` 519 | 520 | ```js 521 | '--name': { 522 | /* ... */ 523 | from: '50%', 524 | to: '100%', 525 | /* ... */ 526 | } 527 | ``` 528 | 529 | ```js 530 | '--name': { 531 | /* ... */ 532 | from: '0', 533 | to: '1turn', 534 | /* ... */ 535 | } 536 | ``` 537 | 538 | ### Animation timing 539 | 540 | Type: `String|Function` Default: `linear` Optional: `true` 541 | 542 | A known timing or a custom function. Easing functions get just one argument, which is a value between 0 and 1 (the percentage of how much of the animation is done). The function should return a value between 0 and 1 as well, but for some timings a value less than 0 or greater than 1 is just fine. 543 | 544 | Known timings: `backInOut`, `backIn`, `backOut`, `bounceInOut`, `bounceIn`, `bounceOut`, `circInOut`, `circIn`, `circOut`, `cubicInOut`, `cubicIn`, `cubicOut`, `elasticInOut`, `elasticIn`, `elasticOut`, `expoInOut`, `expoIn`, `expoOut`, `linear`, `quadInOut`, `quadIn`, `quadOut`, `quartInOut`, `quartIn`, `quartOut`, `quintInOut`, `quintIn`, `quintOut`, `sineInOut`, `sineIn`, `sineOut` 545 | 546 | Examples: 547 | 548 | ```js 549 | '--name': { 550 | /* ... */ 551 | timing: 'circInOut' 552 | } 553 | ``` 554 | 555 | ```js 556 | '--name': { 557 | /* ... */ 558 | timing: (t) => t * t 559 | } 560 | ``` 561 | 562 | ## Related 563 | 564 | - [ngx-basicscroll](https://github.com/theunreal/ngx-basicscroll) - Angular wrapper for basicScroll 565 | - [react-basic-scroll](https://github.com/liorbd/react-basic-scroll) - React wrapper for basicScroll 566 | 567 | ## Tips 568 | 569 | - Only animate `transform` and `opacity` and use `will-change` to [hint browsers about the kind of changes](https://developer.mozilla.org/de/docs/Web/CSS/will-change). This way the browser can setup appropriate optimizations ahead of time before the element is actually changed. 570 | - Keep the amount of instances low. More instances means more checks, calculations and style changes. 571 | - Don't animate everything at once and don't animate too many properties. Browsers don't like this. 572 | - Smooth animations by adding a short transition to the element: `transform: translateY(var(--ty)); transition: transform .1s`. 573 | - basicScroll applies all [props](#props) globally by default. Try to reuse variables across elements instead of creating more instances. -------------------------------------------------------------------------------- /bower.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "basicScroll", 3 | "authors": [ 4 | "Tobias Reich " 5 | ], 6 | "description": "Standalone parallax scrolling for mobile and desktop with CSS variables", 7 | "main": [ 8 | "dist/basicScroll.min.js" 9 | ], 10 | "keywords": [], 11 | "ignore": [ 12 | "**/.*", 13 | "demos", 14 | "build.js", 15 | "package.json" 16 | ], 17 | "license": "MIT", 18 | "homepage": "https://github.com/electerious/basicScroll", 19 | "repository": { 20 | "type": "git", 21 | "url": "https://github.com/electerious/basicScroll.git" 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /build.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const { writeFile } = require('fs').promises 4 | const js = require('rosid-handler-js') 5 | 6 | js('src/scripts/main.js', { 7 | 8 | optimize: true, 9 | browserify: { 10 | standalone: 'basicScroll' 11 | } 12 | 13 | }).then((data) => { 14 | 15 | return writeFile('dist/basicScroll.min.js', data) 16 | 17 | }) -------------------------------------------------------------------------------- /demos/callback.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | basicScroll Demo 6 | 7 | 8 | 9 | 36 | 37 |
38 | 39 | 40 | 41 | 42 | 43 | 44 |
45 | 46 | 47 | 48 | 49 | 70 | 71 | -------------------------------------------------------------------------------- /demos/default.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | basicScroll Demo 6 | 7 | 8 | 9 | 50 | 51 |
52 |
53 |
54 |
55 |
56 |
57 |
58 | 59 |
60 |
rotate
61 |
fade
62 |
63 | 64 |
65 |
reference
66 |
direct
67 |
68 | 69 | 70 | 71 | 145 | 146 | -------------------------------------------------------------------------------- /dist/basicScroll.min.js: -------------------------------------------------------------------------------- 1 | !function(t){if("object"==typeof exports&&"undefined"!=typeof module)module.exports=t();else if("function"==typeof define&&define.amd)define([],t);else{("undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof self?self:this).basicScroll=t()}}((function(){return function t(n,o,e){function r(i,c){if(!o[i]){if(!n[i]){var f="function"==typeof require&&require;if(!c&&f)return f(i,!0);if(u)return u(i,!0);var a=new Error("Cannot find module '"+i+"'");throw a.code="MODULE_NOT_FOUND",a}var s=o[i]={exports:{}};n[i][0].call(s.exports,(function(t){return r(n[i][1][t]||t)}),s,s.exports,t,n,o,e)}return o[i].exports}for(var u="function"==typeof require&&require,i=0;i2&&void 0!==arguments[2]?arguments[2]:l(),e=arguments.length>3&&void 0!==arguments[3]?arguments[3]:d(),r=n.getBoundingClientRect(),u=t.match(/^[a-z]+/)[0],i=t.match(/[a-z]+$/)[0],c=0;return"top"===i&&(c-=0),"middle"===i&&(c-=e/2),"bottom"===i&&(c-=e),"top"===u&&(c+=r.top+o),"middle"===u&&(c+=r.top+o+r.height/2),"bottom"===u&&(c+=r.top+o+r.height),"".concat(c,"px")},v=function(t){var n=arguments.length>1&&void 0!==arguments[1]?arguments[1]:l(),o=t.getData(),e=o.to.value-o.from.value,r=n-o.from.value,u=r/(e/100),i=Math.min(Math.max(u,0),100),c=w(o.direct,{global:document.documentElement,elem:o.elem,direct:o.direct}),f=Object.keys(o.props).reduce((function(t,n){var e=o.props[n],r=e.from.unit||e.to.unit,u=e.from.value-e.to.value,c=e.timing(i/100),f=e.from.value-u*c,a=Math.round(1e4*f)/1e4;return t[n]=a+r,t}),{}),a=u>=0&&u<=100,s=u<0||u>100;return!0===a&&o.inside(t,u,f),!0===s&&o.outside(t,u,f),{elem:c,props:f}},x=function(t,n){Object.keys(n).forEach((function(o){return function(t,n){t.style.setProperty(n.key,n.value)}(t,{key:o,value:n[o]})}))};o.create=function(t){var n=null,o=!1,e={isActive:function(){return o},getData:function(){return n},calculate:function(){n=function(){var t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{};if(null==(t=Object.assign({},t)).inside&&(t.inside=function(){}),null==t.outside&&(t.outside=function(){}),null==t.direct&&(t.direct=!1),null==t.track&&(t.track=!0),null==t.props&&(t.props={}),null==t.from)throw new Error("Missing property `from`");if(null==t.to)throw new Error("Missing property `to`");if("function"!=typeof t.inside)throw new Error("Property `inside` must be undefined or a function");if("function"!=typeof t.outside)throw new Error("Property `outside` must be undefined or a function");if("boolean"!=typeof t.direct&&t.direct instanceof HTMLElement==0)throw new Error("Property `direct` must be undefined, a boolean or a DOM element/node");if(!0===t.direct&&null==t.elem)throw new Error("Property `elem` is required when `direct` is true");if("boolean"!=typeof t.track)throw new Error("Property `track` must be undefined or a boolean");if("object"!==i(t.props))throw new Error("Property `props` must be undefined or an object");if(null==t.elem){if(!1===m(t.from))throw new Error("Property `from` must be a absolute value when no `elem` has been provided");if(!1===m(t.to))throw new Error("Property `to` must be a absolute value when no `elem` has been provided")}else!0===h(t.from)&&(t.from=y(t.from,t.elem)),!0===h(t.to)&&(t.to=y(t.to,t.elem));return t.from=b(t.from),t.to=b(t.to),t.props=Object.keys(t.props).reduce((function(n,o){var e=Object.assign({},t.props[o]);if(!1===m(e.from))throw new Error("Property `from` of prop must be a absolute value");if(!1===m(e.to))throw new Error("Property `from` of prop must be a absolute value");if(e.from=b(e.from),e.to=b(e.to),null==e.timing&&(e.timing=r.default.linear),"string"!=typeof e.timing&&"function"!=typeof e.timing)throw new Error("Property `timing` of prop must be undefined, a string or a function");if("string"==typeof e.timing&&null==r.default[e.timing])throw new Error("Unknown timing for property `timing` of prop");return"string"==typeof e.timing&&(e.timing=r.default[e.timing]),n[o]=e,n}),{}),t}(t)},update:function(){var t=v(e),n=t.elem,o=t.props;return x(n,o),o},start:function(){o=!0},stop:function(){o=!1},destroy:function(){s[u]=void 0}},u=s.push(e)-1;return e.calculate(),e},!0===p?(!function t(n,o){var e=function(){requestAnimationFrame((function(){return t(n,o)}))},r=function(t){return t.filter((function(t){return null!=t&&t.isActive()}))}(s);if(0===r.length)return e();var u=l();if(o===u)return e();o=u,r.map((function(t){return v(t,u)})).forEach((function(t){var n=t.elem,o=t.props;return x(n,o)})),e()}(),window.addEventListener("resize",(c=function(){(function(t){return t.filter((function(t){return null!=t&&t.getData().track}))})(s).forEach((function(t){t.calculate(),t.update()}))},f=50,a=null,function(){for(var t=arguments.length,n=new Array(t),o=0;o" 6 | ], 7 | "description": "Standalone parallax scrolling for mobile and desktop with CSS variables", 8 | "main": "dist/basicScroll.min.js", 9 | "keywords": [ 10 | "parallax", 11 | "scroll", 12 | "scrolling" 13 | ], 14 | "scripts": { 15 | "build": "node build.js" 16 | }, 17 | "license": "MIT", 18 | "homepage": "https://github.com/electerious/basicScroll", 19 | "repository": { 20 | "type": "git", 21 | "url": "https://github.com/electerious/basicScroll.git" 22 | }, 23 | "files": [ 24 | "dist", 25 | "src" 26 | ], 27 | "dependencies": { 28 | "eases": "^1.0.8", 29 | "parse-unit": "^1.0.1" 30 | }, 31 | "devDependencies": { 32 | "rosid-handler-js": "^13.0.0" 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /src/scripts/main.js: -------------------------------------------------------------------------------- 1 | import parseUnit from 'parse-unit' 2 | import eases from 'eases' 3 | 4 | const instances = [] 5 | const isBrowser = typeof window !== 'undefined' 6 | 7 | /** 8 | * Debounces a function that will be triggered many times. 9 | * @param {Function} fn 10 | * @param {Number} duration 11 | * @returns {Function} 12 | */ 13 | const debounce = function(fn, duration) { 14 | 15 | let timeout = null 16 | 17 | return (...args) => { 18 | 19 | clearTimeout(timeout) 20 | 21 | timeout = setTimeout(() => fn(...args), duration) 22 | 23 | } 24 | 25 | } 26 | 27 | /** 28 | * Returns all active instances from an array. 29 | * @param {Array} instances 30 | * @returns {Array} instances - Active instances. 31 | */ 32 | const getActiveInstances = function(instances) { 33 | 34 | return instances.filter((instance) => instance != null && instance.isActive()) 35 | 36 | } 37 | 38 | /** 39 | * Returns all tracked instances from an array. 40 | * @param {Array} instances 41 | * @returns {Array} instances - Tracked instances. 42 | */ 43 | const getTrackedInstances = function(instances) { 44 | 45 | return instances.filter((instance) => instance != null && instance.getData().track) 46 | 47 | } 48 | 49 | 50 | /** 51 | * Returns the number of scrolled pixels. 52 | * @returns {Number} scrollTop 53 | */ 54 | const getScrollTop = function() { 55 | 56 | // Use scrollTop because it's faster than getBoundingClientRect() 57 | return (document.scrollingElement || document.documentElement).scrollTop 58 | 59 | } 60 | 61 | /** 62 | * Returns the height of the viewport. 63 | * @returns {Number} viewportHeight 64 | */ 65 | const getViewportHeight = function() { 66 | 67 | return (window.innerHeight || window.outerHeight) 68 | 69 | } 70 | 71 | /** 72 | * Checks if a value is absolute. 73 | * An absolute value must have a value that's not NaN. 74 | * @param {String|Integer} value 75 | * @returns {Boolean} isAbsolute 76 | */ 77 | const isAbsoluteValue = function(value) { 78 | 79 | return isNaN(parseUnit(value)[0]) === false 80 | 81 | } 82 | 83 | /** 84 | * Parses an absolute value. 85 | * @param {String|Integer} value 86 | * @returns {Object} value - Parsed value. 87 | */ 88 | const parseAbsoluteValue = function(value) { 89 | 90 | const parsedValue = parseUnit(value) 91 | 92 | return { 93 | value: parsedValue[0], 94 | unit: parsedValue[1] 95 | } 96 | 97 | } 98 | 99 | /** 100 | * Checks if a value is relative. 101 | * A relative value must start and end with [a-z] and needs a '-' in the middle. 102 | * @param {String|Integer} value 103 | * @returns {Boolean} isRelative 104 | */ 105 | const isRelativeValue = function(value) { 106 | 107 | return String(value).match(/^[a-z]+-[a-z]+$/) !== null 108 | 109 | } 110 | 111 | /** 112 | * Returns the property that should be used according to direct. 113 | * @param {Boolean|Node} direct 114 | * @param {Object} properties 115 | * @returns {*} 116 | */ 117 | const mapDirectToProperty = function(direct, properties) { 118 | 119 | if (direct === true) return properties.elem 120 | if (direct instanceof HTMLElement === true) return properties.direct 121 | 122 | return properties.global 123 | 124 | } 125 | 126 | /** 127 | * Converts a relative value to an absolute value. 128 | * @param {String} value 129 | * @param {Node} elem - Anchor of the relative value. 130 | * @param {?Integer} scrollTop - Pixels scrolled in document. 131 | * @param {?Integer} viewportHeight - Height of the viewport. 132 | * @returns {String} value - Absolute value. 133 | */ 134 | const relativeToAbsoluteValue = function(value, elem, scrollTop = getScrollTop(), viewportHeight = getViewportHeight()) { 135 | 136 | const elemSize = elem.getBoundingClientRect() 137 | 138 | const elemAnchor = value.match(/^[a-z]+/)[0] 139 | const viewportAnchor = value.match(/[a-z]+$/)[0] 140 | 141 | let y = 0 142 | 143 | if (viewportAnchor === 'top') y -= 0 144 | if (viewportAnchor === 'middle') y -= viewportHeight / 2 145 | if (viewportAnchor === 'bottom') y -= viewportHeight 146 | 147 | if (elemAnchor === 'top') y += (elemSize.top + scrollTop) 148 | if (elemAnchor === 'middle') y += (elemSize.top + scrollTop) + elemSize.height / 2 149 | if (elemAnchor === 'bottom') y += (elemSize.top + scrollTop) + elemSize.height 150 | 151 | return `${ y }px` 152 | 153 | } 154 | 155 | /** 156 | * Validates data and sets defaults for undefined properties. 157 | * @param {?Object} data 158 | * @returns {Object} data - Validated data. 159 | */ 160 | const validate = function(data = {}) { 161 | 162 | // Copy root object to avoid changes by reference 163 | data = Object.assign({}, data) 164 | 165 | if (data.inside == null) data.inside = () => {} 166 | if (data.outside == null) data.outside = () => {} 167 | if (data.direct == null) data.direct = false 168 | if (data.track == null) data.track = true 169 | if (data.props == null) data.props = {} 170 | 171 | if (data.from == null) throw new Error('Missing property `from`') 172 | if (data.to == null) throw new Error('Missing property `to`') 173 | if (typeof data.inside !== 'function') throw new Error('Property `inside` must be undefined or a function') 174 | if (typeof data.outside !== 'function') throw new Error('Property `outside` must be undefined or a function') 175 | if (typeof data.direct !== 'boolean' && data.direct instanceof HTMLElement === false) throw new Error('Property `direct` must be undefined, a boolean or a DOM element/node') 176 | if (data.direct === true && data.elem == null) throw new Error('Property `elem` is required when `direct` is true') 177 | if (typeof data.track !== 'boolean') throw new Error('Property `track` must be undefined or a boolean') 178 | if (typeof data.props !== 'object') throw new Error('Property `props` must be undefined or an object') 179 | 180 | if (data.elem == null) { 181 | 182 | if (isAbsoluteValue(data.from) === false) throw new Error('Property `from` must be a absolute value when no `elem` has been provided') 183 | if (isAbsoluteValue(data.to) === false) throw new Error('Property `to` must be a absolute value when no `elem` has been provided') 184 | 185 | } else { 186 | 187 | if (isRelativeValue(data.from) === true) data.from = relativeToAbsoluteValue(data.from, data.elem) 188 | if (isRelativeValue(data.to) === true) data.to = relativeToAbsoluteValue(data.to, data.elem) 189 | 190 | } 191 | 192 | data.from = parseAbsoluteValue(data.from) 193 | data.to = parseAbsoluteValue(data.to) 194 | 195 | // Create a new props object to avoid changes by reference 196 | data.props = Object.keys(data.props).reduce((acc, key) => { 197 | 198 | // Copy prop object to avoid changes by reference 199 | const prop = Object.assign({}, data.props[key]) 200 | 201 | if (isAbsoluteValue(prop.from) === false) throw new Error('Property `from` of prop must be a absolute value') 202 | if (isAbsoluteValue(prop.to) === false) throw new Error('Property `from` of prop must be a absolute value') 203 | 204 | prop.from = parseAbsoluteValue(prop.from) 205 | prop.to = parseAbsoluteValue(prop.to) 206 | 207 | if (prop.timing == null) prop.timing = eases['linear'] 208 | 209 | if (typeof prop.timing !== 'string' && typeof prop.timing !== 'function') throw new Error('Property `timing` of prop must be undefined, a string or a function') 210 | 211 | if (typeof prop.timing === 'string' && eases[prop.timing] == null) throw new Error('Unknown timing for property `timing` of prop') 212 | if (typeof prop.timing === 'string') prop.timing = eases[prop.timing] 213 | 214 | acc[key] = prop 215 | 216 | return acc 217 | 218 | }, {}) 219 | 220 | return data 221 | 222 | } 223 | 224 | /** 225 | * Calculates the props of an instance. 226 | * @param {Object} instance 227 | * @param {?Integer} scrollTop - Pixels scrolled in document. 228 | * @returns {Object} Calculated props and the element to apply styles to. 229 | */ 230 | const getProps = function(instance, scrollTop = getScrollTop()) { 231 | 232 | const data = instance.getData() 233 | 234 | // 100% in pixel 235 | const total = data.to.value - data.from.value 236 | 237 | // Pixel scrolled 238 | const current = scrollTop - data.from.value 239 | 240 | // Percent scrolled 241 | const precisePercentage = current / (total / 100) 242 | const normalizedPercentage = Math.min(Math.max(precisePercentage, 0), 100) 243 | 244 | // Get the element that should be used according to direct 245 | const elem = mapDirectToProperty(data.direct, { 246 | global: document.documentElement, 247 | elem: data.elem, 248 | direct: data.direct 249 | }) 250 | 251 | // Generate an object with all new props 252 | const props = Object.keys(data.props).reduce((acc, key) => { 253 | 254 | const prop = data.props[key] 255 | 256 | // Use the unit of from OR to. It's valid to animate from '0' to '100px' and 257 | // '0' should be treated as 'px', too. Unit will be an empty string when no unit given. 258 | const unit = prop.from.unit || prop.to.unit 259 | 260 | // The value that should be interpolated 261 | const diff = prop.from.value - prop.to.value 262 | 263 | // All easing functions only remap a time value, and all have the same signature. 264 | // Typically a value between 0 and 1, and it returns a new float that has been eased. 265 | const time = prop.timing(normalizedPercentage / 100) 266 | 267 | const value = prop.from.value - diff * time 268 | 269 | // Round to avoid unprecise values. 270 | // The precision of floating point computations is only as precise as the precision it uses. 271 | // http://stackoverflow.com/questions/588004/is-floating-point-math-broken 272 | const rounded = Math.round(value * 10000) / 10000 273 | 274 | acc[key] = rounded + unit 275 | 276 | return acc 277 | 278 | }, {}) 279 | 280 | // Use precise percentage to check if the viewport is between from and to. 281 | // Would always return true when using the normalized percentage. 282 | const isInside = (precisePercentage >= 0 && precisePercentage <= 100) 283 | const isOutside = (precisePercentage < 0 || precisePercentage > 100) 284 | 285 | // Execute callbacks 286 | if (isInside === true) data.inside(instance, precisePercentage, props) 287 | if (isOutside === true) data.outside(instance, precisePercentage, props) 288 | 289 | return { 290 | elem, 291 | props 292 | } 293 | 294 | } 295 | 296 | /** 297 | * Adds a property with the specified name and value to a given style object. 298 | * @param {Node} elem - Styles will be applied to this element. 299 | * @param {Object} prop - Object with a key and value. 300 | */ 301 | const setProp = function(elem, prop) { 302 | 303 | elem.style.setProperty(prop.key, prop.value) 304 | 305 | } 306 | 307 | /** 308 | * Adds properties to a given style object. 309 | * @param {Node} elem - Styles will be applied to this element. 310 | * @param {Object} props - Object of props. 311 | */ 312 | const setProps = function(elem, props) { 313 | 314 | Object.keys(props).forEach((key) => setProp(elem, { 315 | key: key, 316 | value: props[key] 317 | })) 318 | 319 | } 320 | 321 | /** 322 | * Gets and sets new props when the user has scrolled and when there are active instances. 323 | * This part get executed with every frame. Make sure it's performant as hell. 324 | * @param {Object} style - Style object. 325 | * @param {?Integer} previousScrollTop 326 | * @returns {?*} 327 | */ 328 | const loop = function(style, previousScrollTop) { 329 | 330 | // Continue loop 331 | const repeat = () => { 332 | 333 | // It depends on the browser, but it turns out that closures 334 | // are sometimes faster than .bind or .apply. 335 | requestAnimationFrame(() => loop(style, previousScrollTop)) 336 | 337 | } 338 | 339 | // Get all active instances 340 | const activeInstances = getActiveInstances(instances) 341 | 342 | // Only continue when active instances available 343 | if (activeInstances.length === 0) return repeat() 344 | 345 | const scrollTop = getScrollTop() 346 | 347 | // Only continue when scrollTop has changed 348 | if (previousScrollTop === scrollTop) return repeat() 349 | else previousScrollTop = scrollTop 350 | 351 | // Get and set new props of each instance 352 | activeInstances 353 | .map((instance) => getProps(instance, scrollTop)) 354 | .forEach(({ elem, props }) => setProps(elem, props)) 355 | 356 | repeat() 357 | 358 | } 359 | 360 | /** 361 | * Creates a new instance. 362 | * @param {Object} data 363 | * @returns {Object} instance 364 | */ 365 | export const create = function(data) { 366 | 367 | // Store the parsed data 368 | let _data = null 369 | 370 | // Store if instance is started or stopped 371 | let active = false 372 | 373 | // Returns if instance is started or stopped 374 | const _isActive = () => { 375 | 376 | return active 377 | 378 | } 379 | 380 | // Returns the parsed and calculated data 381 | const _getData = function() { 382 | 383 | return _data 384 | 385 | } 386 | 387 | // Parses and calculates data 388 | const _calculate = function() { 389 | 390 | _data = validate(data) 391 | 392 | } 393 | 394 | // Update props 395 | const _update = () => { 396 | 397 | // Get new props 398 | const { elem, props } = getProps(instance) 399 | 400 | // Set new props 401 | setProps(elem, props) 402 | 403 | return props 404 | 405 | } 406 | 407 | // Starts to animate 408 | const _start = () => { 409 | 410 | active = true 411 | 412 | } 413 | 414 | // Stops to animate 415 | const _stop = () => { 416 | 417 | active = false 418 | 419 | } 420 | 421 | // Destroys the instance 422 | const _destroy = () => { 423 | 424 | // Replace instance instead of deleting the item to avoid 425 | // that the index of other instances changes. 426 | instances[index] = undefined 427 | 428 | } 429 | 430 | // Assign instance to a variable so the instance can be used 431 | // elsewhere in the current function. 432 | const instance = { 433 | isActive: _isActive, 434 | getData: _getData, 435 | calculate: _calculate, 436 | update: _update, 437 | start: _start, 438 | stop: _stop, 439 | destroy: _destroy 440 | } 441 | 442 | // Store instance in global array and save the index 443 | const index = instances.push(instance) - 1 444 | 445 | // Calculate data for the first time 446 | instance.calculate() 447 | 448 | return instance 449 | 450 | } 451 | 452 | // Only run basicScroll when executed in a browser environment 453 | if (isBrowser === true) { 454 | 455 | // Start to loop 456 | loop() 457 | 458 | // Recalculate and update instances when the window size changes 459 | window.addEventListener('resize', debounce(() => { 460 | 461 | // Get all tracked instances 462 | const trackedInstances = getTrackedInstances(instances) 463 | 464 | trackedInstances.forEach((instance) => { 465 | instance.calculate() 466 | instance.update() 467 | }) 468 | 469 | }, 50)) 470 | 471 | } else { 472 | 473 | console.warn('basicScroll is not executing because you are using it in an environment without a `window` object') 474 | 475 | } --------------------------------------------------------------------------------