scroll-stash

    1.1.2 • Public • Published

    scroll-stash

    A JavaScript plugin to help preserve an element's scroll position.

    NPM Version Build Status Coverage Status

    CodePen Example

    Installation

    npm install scroll-stash
    

    JavaScript

    Import and instantiate ScrollStash in your scripts:

    import ScrollStash from 'scroll-stash';
    const scrollStash = new ScrollStash({ autoInit: true });

    It's also possible to include ScrollStash using a script tag:

    <!-- Via NPM -->
    <script src="./node_modules/scroll-stash/dist/scripts.umd.js"></script>
    
    <!-- Via CDN -->
    <script src="https://unpkg.com/scroll-stash"></script>
    
    <!-- Instantiate ScrollStash in your scripts -->
    <script>
    const scrollStash = new ScrollStash();
    scrollStash.init();
    </script>

    Styles

    There are no styles to include for scroll-stash, but if you plan on using the anchor feature it's important to make sure:

    • The scrollable element has position: relative applied.
    • The anchor's nearest parent with position: relative should be the scrollable container.
    • If a parent wrapper of an anchor exists that needs to be positioned relatively, pass it's selector as the selectorAnchorParent option.

    Markup

    The most basic implementation of scroll-stash is the application of the data attribute data-scroll-stash with a unique ID as the value. The unique ID is used in saving each scroll-stash element's scroll position.

    <div data-scroll-stash="[unique-id]">
      ...
    </div>

    data-scroll-stash-anchor

    This optional data attribute—when set on a scroll-stash element with a valid selector—defines an anchor that will take precedence over set options on instantiation. Setting it's value to ignore or false will disable the anchor feature. This is useful to prevent a parent scrollable wrapper from inheriting the anchor of child elements.

    <div data-scroll-stash="[unique-id]" data-scroll-stash-anchor="[selector | ignore | false]">
      ...
    </div>

    Anchors are elements within a scrollable container that you want to always be visible. In the case where a preserved scroll position is applied and the anchor is not visible, the scroll will be adjusted to the nearest position to make the entire element visible with the appropriate padding or clearance elements as defined in options.

    Options

    Key Default Description
    autoInit false Automatically instantiates the instance.
    dataScroll 'scroll-stash' Data attribute for a scroll-stash element. Stores the unique ID for saving and restoring scroll positions.
    dataAnchor 'scroll-stash-anchor' Data attribute for setting an element specific anchor or disabling the anchor feature on a specific scroll-stash element.
    selectorAnchor '' Selector for the anchor to look for in each scroll-stash element.
    selectorAnchorParent '' Parent selector for anchors who are wrapped in elements with position: relative styles.
    selectorTopElem '' Selector for sticky or fixed top element within a scroll-stash that anchors need to take into account.
    selectorBotElem '' Selector for sticky or fixed bottom element within a scroll-stash that anchors need to take into account.
    alignment 'nearest' Defines the vertical alignment of scroll anchor. Can be set to start, end or nearest.
    behavior 'auto' Defines the transition animation. Can either be set to auto or smooth.
    anchorPadding 16 The extra padding to provide when scrolling anchors into view.
    saveKey 'ScrollStash' The key that is used to save the scroll stash state object in local storage.
    throttleDelay 250 The delay to apply between scroll stash saves. Since scrolling events fire extremely fast, this creates a throttle to help improve performance.
    customEventPrefix 'scroll-stash:' Prefix to be used on custom events.

    Events

    • scroll-stash:saved Emits when scroll positions are saved.
    • scroll-stash:applied Emits when scroll positions are applied.
    • scroll-stash:anchor Emits when the anchor is scrolled into view.

    API

    scrollStash.init(options)

    Initializes the scroll-stash instance.

    Parameters

    • options (optional) An options object. This will be merged with the options passed during instantiation.
    const scrollStash = new ScrollStash();
    scrollStash.init();
    
    // Or, pass in some options:
    scrollStash.init({
      selectorAnchor: '.asdf',
      anchorPadding: 20
    });

    scrollStash.destroy()

    Destroys the previously initialized scroll-stash instance.

    const scrollStash = new ScrollStash();
    scrollStash.init();
    // ...
    scrollStash.destroy();

    scrollStash.anchorShow(element, behavior)

    Scrolls the anchor in view of the passed scroll-stash HTML element.

    Parameters

    • element HTML element that scroll stash has been instantiated on.
    • behavior (optional) The transition animation. Can either be set to auto or smooth. Defaults to behavior option.
    const el = document.querySelector('[data-scroll-stash]');
    const result = scrollStash.anchorShow(el);
    // Returns: Object with result details
    // If scrolled:
    //   { scrolled: { value: [position], behavior: [behavior] }, msg: 'Anchor was scrolled into view' }
    // If failed because anchor is already in view:
    //   { scrolled: false, msg: 'Anchor is already in view' }
    // If failed because anchor was not found:
    //   { scrolled: false, msg: 'Anchor was not found' }

    scrollStash.anchorGet(element)

    Returns the anchor element of the passed scroll-stash HTML element.

    Parameters

    • element HTML element that scroll stash has been instantiated on.
    const el = document.querySelector('[data-scroll-stash]');
    const anchor = scrollStash.anchorGet(el);
    // Returns: HTMLElement Object

    Copyright and License

    Scroll-stash copyright (c) 2020 Sebastian Nitu. Scroll-stash is released under the MIT license.

    Install

    npm i scroll-stash

    DownloadsWeekly Downloads

    36

    Version

    1.1.2

    License

    MIT

    Unpacked Size

    133 kB

    Total Files

    32

    Last publish

    Collaborators

    • sebnitu