Nefariously Programmed Mecha

    scroll-to-position
    TypeScript icon, indicating that this package has built-in type declarations

    1.7.11 • Public • Published

    scroll-to-position

    Animate scroll to either an x, y, or x and y position in any scrollable viewport with customisable easing.

    Demo

    GitHub release Build Status Codacy Badge

    Install

    You can install via npm or yarn.

    npm

    npm install --save scroll-to-position

    yarn

    yarn add scroll-to-position

    Usage

    Importing

    You can import using ES6 imports.

    import { ScrollTo } from 'scroll-to-position';

    Arguments

    ScrollTo accepts two arguments:

    target: either a position ([positionX, positionY]) or a HTML Element (e.g. a reference to a div).

    options (optional): an object of configuration options - see the options section below.

    Examples

    Position

    ScrollTo([0, 100]);

    Element

    const myElement = document.querySelector('.MyElement');
    ScrollTo(myElement);

    Note: if you're using TypeScript you will most likely need to cast your element to a HTMLElement, as document.querySelector returns a Element type.

    Callback

    Calling ScrollTo returns a Promise, so it is possible to run your own code after scrolling has completed.

    ScrollTo([0, 100]).then(() => console.log('Scrolling completed'));

    If cancelOnUserScroll is enabled and the user interrupts scrolling, then the promise rejects and can be caught using Promise.prototype.catch

    ScrollTo([0, 100])
      .then(() => console.log('Scrolling completed'))
      .catch(() => console.log('User interrupted scrolling'));

    Options

    When calling ScrollTo you can provide an options object, with values to override the defaults.

    Option Parameters

    Parameter Type Description Default
    scrollContainer HTMLElement or Window The area to scroll. e.g. window or a div with overflow auto window
    offset Position ([number, number]) If your target is a HTMLElement you may want to provide an offset to prevent scrolling right to the edge of the element [0,0]
    duration DurationRange ([number, number]) or Duration (number) Either a DurationRange ([minDuration, maxDuration]) or a set duration (all values in milliseconds). If you provide a range the scroll distance (providing it's no less than the minDuration and no more than the maxDuration will be used as the duration) [200, 5000]
    easing string The easing function the animation will use. The easing's available can be seen in my js-easing-functions repo (https://github.com/bameyrick/js-easing-functions) https://github.com/bameyrick/js-easing-functions
    cancelOnUserScroll boolean Whether the scroll animation should stop when the user scrolls true
    animate boolean Whether ScrollTo should animate to the target, or jump straight there with no animation true
    autoDurationMultiplier number If duration is to picked automatically (between DurationRange), multiply the distance to travel by this value to get the duration 2
    onlyScrollIfNotInView boolean Only scroll if the target is not within the viewport of the scrollable area. If the provided target is a DOM element then it will check to see if the element is fully within the scroll area. false

    Example of providing options

    ScrollTo([0, 100], {
      duration: [300, 1000],
      easing: 'easeInOutSine',
    });

    Using the easing enum in TypeScript

    import { ScrollTo, Easing } from 'scroll-to-position';
    
    ScrollTo([0, 100], {
      duration: [300, 1000],
      easing: Easing.easeInQuad,
    });

    Extras

    An autoScroll boolean is added to the window which you can use in your scroll event listeners to check if the window is being autoScrolled by this package.

    Install

    npm i scroll-to-position

    DownloadsWeekly Downloads

    89

    Version

    1.7.11

    License

    MIT

    Unpacked Size

    407 kB

    Total Files

    11

    Last publish

    Collaborators

    • bameyrick