• Stars
    star
    381
  • Rank 112,502 (Top 3 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created about 8 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Lightweight scroll to function with a powerful API.

animated-scroll-to

npm version npm downloads

Lightweight (1.45kb gzipped) scroll to function with a powerful API. Scrolls window or any other DOM element.

The main difference to other libraries is that it accepts speed of scrolling instead of duration. This way scrolling for 200 pixels will last less than scrolling 10000 pixels. Minimum and maximum duration are configurable and set to reasonable defaults (250 and 3000ms).

All changes are tracked in CHANGELOG.

Demo

Play with the live demo.

Features

  • Accepts speed per 1000px instead of duration
  • Scrolls window or any other DOM element horizontally and vertically
  • Returns a promise with a boolean flag which tells you if desired scroll position was reached (for IE you'll need to include a Promise polyfill)
  • If called multiple times on the same element, it will cancel prior animations
  • Optionally prevent user from scrolling until scrolling animation is finished

Usage

Grab it from npm

npm install animated-scroll-to

and import it in your app

import animateScrollTo from 'animated-scroll-to';

// It returns a promise which will be resolved when scroll animation is finished

animateScrollTo(500).then(hasScrolledToPosition => {
  // scroll animation is finished

  // "hasScrolledToPosition" indicates if page/element
  // was scrolled to a desired position
  // or if animation got interrupted
  if (hasScrolledToPosition) {
    // page is scrolled to a desired position
  } else {
    // scroll animation was interrupted by user
    // or by another call of "animateScrollTo"
  }
});

Method signatures

Library has three ways to call it:

// "y" is a desired vertical scroll position to scroll to
function animateScrollTo(y, options);

// "coords" are an array "[x, y]"
// Where "x" and "y" are desired horizontal and vertical positions to scroll to
// Both "x" and "y" can be null
// which will result in keeping the current scroll position for that axis
function animateScrollTo(coords, options);

// If you pass a DOM element, page will be scrolled to it
function animateScrollTo(scrollToElement, options);

Example usage of each method:

// Scrolls page vertically to 1000px
animateScrollTo(1000);

// Scrolls page horizontally to 1000px but keeps vertical scroll position
animateScrollTo([1000, null]);

// Scrolls page horizontally too 1000px and vertically to 500px
animateScrollTo([1000, 500]);

// Scrolls page both horizontally and vertically to ".my-element"
animateScrollTo(document.querySelector('.my-element'));

Options

Options with their default values:

const defaultOptions = {
  // Indicated if scroll animation should be canceled on user action (scroll/keypress/touch)
  // if set to "false" user input will be disabled until scroll animation is complete
  cancelOnUserAction: true,
  
  // Animation easing function, with "easeOutCubic" as default
  easing: t => (--t) * t * t + 1,
  
  // DOM element that should be scrolled
  // Example: document.querySelector('#element-to-scroll'),
  elementToScroll: window,
  
  // Horizontal scroll offset
  // Practical when you are scrolling to a DOM element and want to add some padding
  horizontalOffset: 0,
  
  // Maximum duration of the scroll animation
  maxDuration: 3000,
  
  // Minimum duration of the scroll animation
  minDuration: 250,
  
  // Duration of the scroll per 1000px
  speed: 500,

  // Vertical scroll offset
  // Practical when you are scrolling to a DOM element and want to add some padding
  verticalOffset: 0,
};

Easing

By default library is using easeOutCubic easing function. You can pass a custom function only considering the t value for the range [0, 1] => [0, 1].

To make things easier I provided a list of common easing function below:

/*
 * Easing Functions
 * https://gist.github.com/gre/1650294
 */
const EasingFunctions = {
  // no easing, no acceleration
  linear: (t) => { return t },
  // accelerating from zero velocity
  easeInQuad: (t) => { return t * t },
  // decelerating to zero velocity
  easeOutQuad: (t) => { return t * (2 - t) },
  // acceleration until halfway, then deceleration
  easeInOutQuad: (t) => { return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t },
  // accelerating from zero velocity 
  easeInCubic: (t) => { return t * t * t },
  // decelerating to zero velocity 
  easeOutCubic: (t) => { return (--t) * t * t + 1 },
  // acceleration until halfway, then deceleration 
  easeInOutCubic: (t) => { return t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1 },
  // accelerating from zero velocity 
  easeInQuart: (t) => { return t * t * t * t },
  // decelerating to zero velocity 
  easeOutQuart: (t) => { return 1 - (--t) * t * t * t },
  // acceleration until halfway, then deceleration
  easeInOutQuart: (t) => { return t < 0.5 ? 8 * t * t * t * t : 1 - 8 * (--t) * t * t * t },
  // accelerating from zero velocity
  easeInQuint: (t) => { return t * t * t * t * t },
  // decelerating to zero velocity
  easeOutQuint: (t) => { return 1 + (--t) * t * t * t * t },
  // acceleration until halfway, then deceleration 
  easeInOutQuint: (t) => { return t < 0.5 ? 16 * t * t * t * t * t : 1 + 16 * (--t) * t * t * t * t }
}

Why?

I wasn't able to find standalone, simple and working solution.

Browser support

Anything that supports requestAnimationFrame and Promise. For Internet Explorer you'll need to add es6-promise polyfill.

For IE9 and lower, you'll to provide requestAnimationFrame polyfill.

For IE8 and lower, you'll need to polyfill Array.forEach as well. Haven't tested this though.

It is missing <insert a feature here>

I really tried to keep simple and lightweight. If you are missing something, feel free to open a pull request.

Version 1

I advise you to use v2, as v1 is deprecated. But it is still available on v1 branch and on npm.

More Repositories

1

react-animate-height

Lightweight React component for animating height using CSS transitions. Slide up/down the element, and animate it to any specific height.
TypeScript
754
star
2

react-plx

React parallax component, powerful and lightweight
TypeScript
686
star
3

skyblue

CSS framework (made with SASS)
HTML
453
star
4

html-canvas-video-player

Play inline videos on iPhone with HTML canvas player.
JavaScript
426
star
5

ThinkPad-Fan-Control

App for managing fan speeds on ThinkPad laptops on Linux
C
119
star
6

webpack-babel-react-revisited

Example repo for webpack/babel/react tutorial - https://stanko.github.io/webpack-babel-react-revisited
JavaScript
94
star
7

mobile-chrome-vh-fix

HTML
75
star
8

react-slider

Simple react slider, with touch support and 0 dependencies
JavaScript
65
star
9

react-image-filter

Lightweight React component, for applying color filters on images, works in all modern browsers plus IE10+ and Edge.
JavaScript
57
star
10

retro-frame

JavaScript
42
star
11

sektor

JavaScript library for creating SVG circle sectors and arcs
JavaScript
41
star
12

neon

Generative art piece made using 2d vector field
JavaScript
37
star
13

offset-polygon

Small, no dependency library for offsetting polygons.
TypeScript
32
star
14

rocketScroll

Pure small JavaScript scroll bar script. Support native mouse wheel scroll. Easy customizable css. Works even in IE8+.
JavaScript
32
star
15

awesome-web-development

List of useful articles and libraries for web development (basically links from our company slack dev channel)
32
star
16

react-window-decorators

Two decorators (higher order components) that inject "window" scroll position, dimensions, orientation and breakpoint to your component's props.
JavaScript
32
star
17

window-scroll-manager

60fps window scroll tracking event
JavaScript
31
star
18

vertigo

A tool that transforms raster images into vectors using two distinct shaders - circular dot grid and variable-width spiral.
TypeScript
31
star
19

aria-progress-range-slider

Fully accessible, lightweight progress bar / range slider component
TypeScript
23
star
20

keen

My personal, minimal setup for building and releasing npm packages
TypeScript
15
star
21

linea

JavaScript vector 3D engine
Go
14
star
22

react-ratio

React aspect ratio component
JavaScript
14
star
23

jquery.rainbowJSON

JSON pretty print, jquery plugin
JavaScript
10
star
24

react-tutorial

JavaScript
8
star
25

Stanko.github.io

My personal blog
SCSS
8
star
26

has-tabbed

Small helper for enabling nicer focus behaviour
HTML
5
star
27

timePicker

Plain JavaScript time picker.
JavaScript
4
star
28

rocketPageFlip

jQuery lib for page turning effect
CSS
4
star
29

react-window

React components that simplify the management of window and body event listeners.
TypeScript
4
star
30

letters-from-sarajevo

Adaptation of the book "Letters From Sarajevo" for web
HTML
4
star
31

generative-swirls

JavaScript
4
star
32

pulsar

Micro creative coding playground
TypeScript
4
star
33

generative-utils

TypeScript
3
star
34

ui-colors-from-an-image

TypeScript
3
star
35

generative-breathe

JavaScript
3
star
36

cca

Create Coding Amsterdam
3
star
37

jquery.responsiveFonts

JQuery plugin which makes fonts responsive
HTML
2
star
38

tailor

A developer tool which tries to simplify inspecting spacings on websites
TypeScript
2
star
39

weekly-code-challenge

JavaScript
1
star
40

slice-pixelate-image

JavaScript
1
star
41

LittleWing

Fullscreen backgrounds jQuery plugin
JavaScript
1
star
42

redux-spark

(Deprecated) Helps significantly reduce amount of boilerplate code when using Redux and Redux Saga
TypeScript
1
star
43

generative-init

JavaScript
1
star
44

cube-3D-rotate-grid

JavaScript
1
star