0.6.3 • Published 3 years ago

potatoscroll v0.6.3

Weekly downloads
16
License
MIT
Repository
github
Last release
3 years ago

PotatoScroll

Custom scrollbar but still native scroll engine.

Demo: https://dobrapyra.github.io/PotatoScroll/

Usage

JS

Standalone library

<script src="./dist/potato-scroll.min.js"></script>

ES6 module

Install
npm install --save potatoscroll
Import
import PotatoScroll from 'potatoscroll';

Initialize

Global create multiple instances
PotatoScroll.create({ selector: '.scroll' });
Individual create of each instance
new PotatoScroll({ el: document.querySelector('.scroll--main') });
new PotatoScroll({ el: document.querySelector('.scroll--nested') });

HTML

Example HTML

<div class="scroll scroll--main">
  <div class="innerBox">
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum.</p>
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum.</p>
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum.</p>
    <div class="scroll scroll--nested">
      <div class="innerBox">
        <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum.</p>
        <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum.</p>
      </div>
    </div>
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Natus voluptatem, dicta fuga saepe vitae vel autem repudiandae, suscipit quae id aliquid voluptate, reprehenderit explicabo dolorum adipisci eaque perferendis sapiente. Ipsum.</p>
  </div>
</div>

CSS

Example CSS

.potatoScroll__mask {
  z-index: 0; }

.potatoScroll__track {
  background-color: rgba(0, 0, 0, 0.1);
  transition: background-color 0.2s; }
  .potatoScroll__track--v {
    width: 4px;
    top: 0;
    bottom: 0;
    right: 0;
    transition: width 0.2s, background-color 0.2s; }
    .potatoScroll__track--v:hover {
      width: 12px; }
    .potatoScroll--arrows .potatoScroll__track--v {
      top: 12px;
      bottom: 12px; }
    [dir=rtl] .potatoScroll__track--v {
      right: auto;
      left: 0; }
  .potatoScroll__track--h {
    height: 4px;
    left: 0;
    right: 0;
    bottom: 0;
    transition: height 0.2s, background-color 0.2s; }
    .potatoScroll__track--h:hover {
      height: 12px; }
    .potatoScroll--arrows .potatoScroll__track--h {
      left: 12px;
      right: 12px; }

.potatoScroll__bar {
  z-index: 1;
  position: absolute;
  background-color: rgba(0, 0, 0, 0.2);
  cursor: pointer;
  transition: background-color 0.2s; }
  .potatoScroll__bar:hover {
    background-color: rgba(0, 0, 0, 0.8); }
  .potatoScroll__bar--v {
    width: 100%;
    height: 100%;
    top: 0;
    left: 0;
    transition: width 0.2s, background-color 0.2s; }
  .potatoScroll__bar--h {
    width: 100%;
    height: 100%;
    left: 0;
    top: 0;
    transition: height 0.2s, background-color 0.2s; }

.potatoScroll__arrow {
  z-index: 1;
  position: absolute;
  background-color: rgba(0, 0, 0, 0.2);
  cursor: pointer;
  transition: background-color 0.2s; }
  .potatoScroll__arrow:hover {
    background-color: rgba(0, 0, 0, 0.8); }
  .potatoScroll__arrow--disabled {
    cursor: default; }
    .potatoScroll__arrow--disabled:hover {
      background-color: rgba(0, 0, 0, 0.2); }
  .potatoScroll__arrow--t, .potatoScroll__arrow--b {
    left: 0;
    width: 100%;
    height: 12px; }
  .potatoScroll__arrow--t {
    top: -12px; }
  .potatoScroll__arrow--b {
    bottom: -12px; }
  .potatoScroll__arrow--l, .potatoScroll__arrow--r {
    top: 0;
    height: 100%;
    width: 12px; }
  .potatoScroll__arrow--l {
    left: -12px; }
  .potatoScroll__arrow--r {
    right: -12px; }

SCSS

Example SCSS

.potatoScroll{
  $rootEl: &;
  $arrowSize: 12px;

  &__mask {
    z-index: 0;
  }

  &__track{
    background-color: rgba(0,0,0,0.1);
    transition: background-color 0.2s;

    &--v{
      width: 4px;
      top: 0;
      bottom: 0;
      right: 0;
      transition: width 0.2s, background-color 0.2s;

      &:hover{
        width: 12px;
      }

      #{$rootEl}--arrows & {
        top: $arrowSize;
        bottom: $arrowSize;
      }

      [dir=rtl] & {
        right: auto;
        left: 0;
      }
    }

    &--h{
      height: 4px;
      left: 0;
      right: 0;
      bottom: 0;
      transition: height 0.2s, background-color 0.2s;

      &:hover{
        height: 12px;
      }

      #{$rootEl}--arrows & {
        left: $arrowSize;
        right: $arrowSize;
      }
    }
  }

  &__bar{
    z-index: 1;
    position: absolute;
    background-color: rgba(0,0,0,0.2);
    cursor: pointer;
    transition: background-color 0.2s;

    &:hover{
      background-color: rgba(0,0,0,0.8);
    }

    &--v{
      width: 100%;
      height: 100%;
      top: 0;
      left: 0;
      transition: width 0.2s, background-color 0.2s;
    }

    &--h{
      width: 100%;
      height: 100%;
      left: 0;
      top: 0;
      transition: height 0.2s, background-color 0.2s;
    }
  }

  &__arrow {
    z-index: 1;
    position: absolute;
    background-color: rgba(0,0,0,0.2);
    cursor: pointer;
    transition: background-color 0.2s;

    &:hover{
      background-color: rgba(0,0,0,0.8);
    }

    &--disabled {
      cursor: default;

      &:hover{
        background-color: rgba(0,0,0,0.2);
      }
    }

    &--t,
    &--b {
      left: 0;
      width: 100%;
      height: $arrowSize;
    }

    &--t {
      top: -$arrowSize;
    }

    &--b {
      bottom: -$arrowSize;
    }

    &--l,
    &--r {
      top: 0;
      height: 100%;
      width: $arrowSize;
    }
    
    &--l {
      left: -$arrowSize;
    }
    
    &--r {
      right: -$arrowSize;
    }
  }
}

Default styles file

<link rel="stylesheet" type="text/css" media="screen" href="./dist/potato-scroll.css" />

Options

All available options with their default values:

// global create
PotatoScroll.create({
  selector: undefined, // required, String - CSS selector string
  // ... // all single instance options exclude el
});

// or / and

// single instance create
new PotatoScroll({
  el: undefined, // required, Element
  maskEl: null, // own maskEl, Element
  scrollEl: null, // own scrollEl, Element
  cssClass: 'potatoScroll', // custom css class name for scrollbar styling
  forceCustom: false, // forces to use custom scrollbar on touch devices and macOS
  forceSize: 20, // offset for forceCustom to hide native scrollbar
  withArrows: false, // add arrow buttons to the tracks
  arrowMove: 40, // offset triggered by single click of arrow button
  onNativeScroll: function(element) {}, // on scroll event
  onScroll: function(progress, element) {}, // throttled on scroll event (progress is in range 0 - 1)
  onTop: function(element) {}, // on top event
  onBottom: function(element) {}, // on bottom event
  onLeft: function(element) {}, // on left event
  onRight: function(element) {}, // on right event
});
OptionTypeDefaultDescription
selectorStringundefinedOnly for create() method
elElementundefinedOnly for single instance constructor (new PotatoScroll())
maskElElementnullOnly for single instance constructor1
scrollElElementnullOnly for single instance constructor1
cssClassString"potatoScroll"Custom css class, all classes are generate in BEM
forceCustomBooleanfalseForces to use custom scrollbar on touch devices and macOS
forceSizeNumber20Offset value used by forceCustom to hide native scrollbar
withArrowsBooleanfalseEnables arrow buttons on the tracks
arrowMoveNumber40Offset value triggered by single click of arrow button
  1. Pass both maskEl & scrollEl to use own DOM tree mode Correct DOM tree example:
<div class="potatoScroll"> <!-- el -->
  <div class="potatoScroll__mask"> <!-- maskEl -->
    <div class="potatoScroll__scroll"> <!-- scrollEl -->
       <!-- scroll content -->
    </div>
  </div>
</div>

Constructors

MethodReturnDescription
new PotatoScroll(options)single PotatoScroll instanceThe el property is required in the options object.
PotatoScroll.create(options)array of PotatoScroll instancesCreates multiple instances by css selector.1The selector property is required in the options object.
  1. A single instance for each element catched by css selector

Methods

MethodReturnDescription
refresh()undefinedRecalculates content size and set scrollbars size
destroy()undefinedDestroys the instance and restore original html
initialize()undefinedReinitializes the instance after destroy

Events

EventArgumentsTriggered by
onNativeScroll(e, el)e {Event} native scroll eventel {Element} the instance's root elementNative scroll event.
onScroll(progressObj, el)progressObj {Object} progress of the scroll in two axis as object {v, h}.1 Each value {Number} is in range 0 - 1el {Element} the instance's root elementThrottled scroll event.2
onTop(el)el {Element} the instance's root elementScroll to top edge
onBottom(el)el {Element} the instance's root elementScroll to bottom edge
onLeft(el)el {Element} the instance's root elementScroll to left edge
onRight(el)el {Element} the instance's root elementScroll to right edge
  1. The v is vertical axis value & this h is horizontal axis value.
  2. This event is throttled using requestAnimationFrame.

by dobrapyra

scrollscrollbarnative scrollcustom scrollbar
@everything-registry/sub-chunk-2464
0.6.3

3 years ago

0.6.2

4 years ago

0.6.1

4 years ago

0.6.0

4 years ago

0.5.1

4 years ago

0.5.0

4 years ago

0.4.0

4 years ago

0.3.0

4 years ago

0.2.0

4 years ago

0.1.0

4 years ago

0.0.1

4 years ago