Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

scrollbooster

Package Overview
Dependencies
Maintainers
1
Versions
15
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

scrollbooster

Enjoyable content drag-to-scroll library

  • 3.0.2
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
16K
increased by1.99%
Maintainers
1
Weekly downloads
 
Created
Source

ScrollBooster

Enjoyable drag-to-scroll micro library (~2KB gzipped). Supports smooth content scroll via mouse/touch dragging, trackpad or mouse wheel. Zero dependencies.

Easy to setup yet flexible enough to support any custom scrolling logic.

Installation

You can install it via npm or yarn package manager or via script tag:

npm i scrollbooster
yarn add scrollbooster
<script src="https://unpkg.com/scrollbooster@2/dist/scrollbooster.min.js"></script>

Usage

The most simple setup with default settings:

import ScrollBooster from 'scrollbooster';

new ScrollBooster({
    viewport: document.querySelector('.viewport'),
    scrollMode: 'transform'
});

Please note that in order to support IE11 you should replace arrow functions and string templates from code examples to supported equivalents or just use Babel.

Options

OptionTypeDefaultDescription
viewportDOM NodenullContent viewport element (required)
contentDOM Nodeviewport child elementScrollable content element inside viewport
scrollModeStringundefinedScroll technique - via CSS transform or natively. Could be 'transform' or 'native'
directionString'all'Scroll direction. Could be 'horizontal', 'vertical' or 'all'
bounceBooleantrueEnables elastic bounce effect when hitting viewport borders
textSelectionBooleanfalseEnables text selection inside viewport
inputsFocusBooleantrueEnables focus for elements: 'input', 'textarea', 'button', 'select' and 'label'
pointerModeString'all'Specify pointer type. Supported values - 'touch' (scroll only on touch devices), 'mouse' (scroll only on desktop), 'all' (mobile and desktop)
frictionNumber0.05Scroll friction factor - how fast scrolling stops after pointer release
bounceForceNumber0.1Elastic bounce effect factor
emulateScrollBooleanfalseEnables mouse wheel/trackpad emulation inside viewport
preventDefaultOnEmulateScrollStringfalsePrevents horizontal or vertical default when emulateScroll is enabled (eg. useful to prevent horizontal trackpad gestures while enabling vertical scrolling). Could be 'horizontal' or 'vertical'.
lockScrollOnDragDirectionStringfalseDetect drag direction and either prevent default mousedown/touchstart event or lock content scroll. Could be 'horizontal', 'vertical' or 'all'
dragDirectionToleranceNumber40Tolerance for horizontal or vertical drag detection
onUpdateFunctionnoopHandler function to perform actual scrolling. Receives scrolling state object with coordinates
onClickFunctionnoopClick handler function. Here you can, for example, prevent default event for click on links. Receives object with scrolling metrics and event object. Calls after each click in scrollable area
onPointerDownFunctionnoopmousedown/touchstart events handler
onPointerUpFunctionnoopmouseup/touchend events handler
onPointerMoveFunctionnoopmousemove/touchmove events handler
onWheelFunctionnoopwheel event handler
shouldScrollFunctionnoopFunction to permit or disable scrolling. Receives object with scrolling state and event object. Calls on pointerdown (mousedown, touchstart) in scrollable area. You can return true or false to enable or disable scrolling

List of methods

MethodDescription
setPositionSets new scroll position in viewport. Receives an object with properties x and y
scrollToSmooth scroll to position in viewport. Receives an object with properties x and y
updateMetricsForces to recalculate elements metrics. Useful for cases when content in scrollable area change its size dynamically
updateOptionsSets option value. All properties from Options config object are supported
getStateReturns current scroll state in a same format as onUpdate
destroyRemoves all instance's event listeners

Full Example

const viewport = document.querySelector('.viewport');
const content = document.querySelector('.scrollable-content');

const sb = new ScrollBooster({
  viewport,
  content,
  bounce: true,
  textSelection: false,
  emulateScroll: true,
  onUpdate: (state) => {
    // state contains useful metrics: position, dragOffset, dragAngle, isDragging, isMoving, borderCollision
    // you can control scroll rendering manually without 'scrollMethod' option:
    content.style.transform = `translate(
      ${-state.position.x}px,
      ${-state.position.y}px
    )`;
  },
  shouldScroll: (state, event) => {
    // disable scroll if clicked on button
    const isButton = event.target.nodeName.toLowerCase() === 'button';
    return !isButton;
  },
  onClick: (state, event, isTouchDevice) => {
    // prevent default link event
    const isLink = event.target.nodeName.toLowerCase() === 'link';
    if (isLink) {
      event.preventDefault();
    }
  }
});

// methods usage examples:
sb.updateMetrics();
sb.scrollTo({ x: 100, y: 100 });
sb.updateOptions({ emulateScroll: false });
sb.destroy();

Live ScrollBooster Examples On CodeSandbox

Browser support

ScrollBooster has been tested in IE 11, Edge and other modern browsers (Chrome, Firefox, Safari).

Special thanks

David DeSandro for his talk "Practical UI Physics".

License

MIT License (c) Ilya Shubin

Keywords

FAQs

Package last updated on 07 Jun 2020

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc