Skip to content

Latest commit

 

History

History
181 lines (150 loc) · 19.2 KB

README.md

File metadata and controls

181 lines (150 loc) · 19.2 KB
Raw

MomentaMouse

Description

MomentaMouse enables mouse-users to use touch-style scrolling and flicking gestures to navigate websites.

Web developers can easily add MomentaMouse functionality to a website.

If you would like to see it in action, check out its demo page as well as the demos at damianmgarcia.com.

Also, check out SmoothScroller. It is a JavaScript module that provides easy-to-use and customizable smooth scrolling functionality for your website and is designed to work well with MomentaMouse.

Features

  • Touch-style scrolling and flicking gestures for mouse-users
  • Automatic scroller creation
  • Easily customize scroll deceleration, border bounciness, cursors, and more.
  • Dispatches custom events so your code can easily react

Installation

Import MomentaMouse:

import { MomentaMouse } from "https://damianmgarcia.com/scripts/modules/momenta-mouse.js";

Usage (Basic)

Automatically Create MomentaMouse Scrollers:

MomentaMouse.autoCreateScrollers();

Manually Create a MomentaMouse Scroller:

MomentaMouse.createScroller(document.querySelector("body"));

Usage (Advanced)

Below is a list of all static and instance methods. Most methods allow for method chaining.

Method names are bolded and are followed by a description of the method's function.

If a method has parameters, they are listed in order below the method description. Parameter names are italicized, and if they have a default value, they are also italicized, followed by a description of the parameter's function. Some parameters are options objects.

Static Methods:

  • autoCreateScrollers — Searches for elements that are potentially scrollable to create MomentaMouse Scrollers. It returns the MomentaMouse class.
    • Options Object:
      • rootSelector — ":root" — A String representing the CSS selector that will be used as the starting point in the process of automatically creating MomentaMouse Scrollers. The rootSelector itself is included in the process. Ancestors of the rootSelector will not be included.
      • activateImmediately — true — A Boolean that determines the activation state of MomentaMouse instances after creation. If set to true, instances will be activated after they are created. If set to false, instances will not be activated after they are created.
      • considerOverflowHiddenAxesNonScrollable — true — A Boolean that determines how autoCreateScrollers handles elements with hidden overflows. If set to true, the horizontal axis of an element will be considered non-scrollable by the MomentaMouse instance if overflow-x is set to hidden, and the vertical axis of an element will be considered non-scrollable by the MomentaMouse instance if overflow-y is set to hidden. If set to false, the horizontal axis of an element will be considered scrollable by the MomentaMouse instance as long as there is scrollable overflow, and the vertical axis of an element will be considered scrollable by the MomentaMouse instance as long as there is scrollable overflow.
      • selectorsToIgnore — [ ] — An Array of selectors that the autoCreateScrollers method will refer to when deciding whether to create scrollers. If an element matches one of the selectors in this list, it will not be used to create a MomentaMouse instance.

  • createScroller — Creates a MomentaMouse scroller. It returns a MomentaMouse instance.
    • scrollContainer — The Element that should gain MomentaMouse functionality.
    • Options Object:
      • activateImmediately — true — A Boolean that determines the activation state of a MomentaMouse instance after creation. If set to true, an instance will be activated after it is created. If set to false, an instance will not be activated after it is created.

  • setAllowQuickToggleKey — Sets whether MomentaMouse temporarily deactivates instances in response to holding down the quick toggle key, which is the Ctrl key. This temporary deactivation allows users to highlight and drag text, images, and links. It returns the MomentaMouse class.
    • allowQuickToggleKey — true — A Boolean that determines how MomentaMouse will respond when the quick toggle key is held down. If set to true, all MomentaMouse instances will be deactivated when the quick toggle key is held down, and then reactivated when the key is let go. If set to false, MomentaMouse will not deactivate instances when the quick toggle key is held down.

  • setSelectorsOfElementsScrollerShouldIgnore — Sets the selectors that MomentaMouse should ignore. It is like calling the preventDefault method; if a pointerdown EventTarget itself or one of its ancestors matches a selector in this list, MomentaMouse will not initiate a momentum scroll. It returns the MomentaMouse class.
    • selectors — [ "input[type=email]", "input[type=number]", "input[type=password]", "input[type=range]", "input[type=search]", "input[type=tel]", "input[type=text]", "input[type=url]", "select", "textarea", ] — An Array of selectors that should be ignored by MomentaMouse.
    • Options Object:
      • keepCurrentSelectors — true — A Boolean that determines how new selectors are added. If set to true, the new selectors will be added to the current list of selectors. If set to false, the new selectors will overwrite the current list of selectors.

  • setSelectorsOfClickableElements — Sets the selectors that MomentaMouse should provide wiggle room for so that they can receive click events. This wiggle room ensures that interactive elements can receive clicks while also allowing MomentaMouse to regain control and perform its functions when appropriate. It returns the MomentaMouse class.
    • selectors — [ "a", "button", "details", "input[type=button]", "input[type=checkbox]", "input[type=color]", "input[type=date]", "input[type=datetime-local]", "input[type=file]", "input[type=image]", "input[type=month]", "input[type=radio]", "input[type=reset]", "input[type=submit]", "input[type=time]", "input[type=week]", "summary", ] — An Array of selectors of elements that need to be able to receive click events.
    • Options Object:
      • keepCurrentSelectors — true — A Boolean that determines how new selectors are added. If set to true, the new selectors will be added to the current list of selectors. If set to false, the new selectors will overwrite the current list of selectors.

  • setSelectorsOfOtherTouchScrollers — Sets the selectors that MomentaMouse should provide wiggle room for so that they can perform their own touch-scrolling-like functionality. This wiggle room ensures that they can scroll as intended while also allowing MomentaMouse to regain control and perform its functions when appropriate. It returns the MomentaMouse class.
    • selectors — [ ] — An Array of selectors of elements that have touch-scrolling-like functionality similar to MomentaMouse.
    • Options Object:
      • keepCurrentSelectors — true — A Boolean that determines how new selectors are added. If set to true, the new selectors will be added to the current list of selectors. If set to false, the new selectors will overwrite the current list of selectors.

  • getScroller — Gets and returns a MomentaMouse instance if found, which gives you access to its methods; Otherwise, returns undefined.
    • scrollContainer — The Element that has MomentaMouse functionality.

  • getAllScrollers — Gets and returns an Array of all MomentaMouse instances. The forEach method may then be called to perform batch operations.

Instance Methods:

  • getScrollerData — Gets and returns an Object containing the following instance properties: active, isCurrentlyHandlingPointer, scrollContainer, scrollableAxes, scrolling.

  • setDecelerationLevel — Sets the deceleration of momentum scrolls. It returns the MomentaMouse instance.
    • decelerationLevel — "medium" — A String representing the deceleration level, which may be any of the following values: "none", "minimum", "low", "medium", "high", or "maximum".

  • setBorderBouncinessLevel — Sets the bounciness of borders impacted by momentum scrolls. It returns the MomentaMouse instance.
    • borderBouncinessLevel — "medium" — A String representing the border bounciness level, which may be any of the following values: "none", "minimum", "low", "medium", "high", or "maximum". Bouncing and overscroll effects are accomplished with CSS transforms, and therefore any value other than "none" will add a CSS transform declaration to the scrollContainer. Keep in mind that an element with a transform declaration value other than "none" will become a containing block for descendant elements that have position values of absolute or fixed. For fixed-position descendant elements, this means they will become fixed to the containing block rather than the viewport.

  • setGrabCursor — Sets the grab cursor. It returns the MomentaMouse instance.
  • setGrabbingCursor — Sets the grabbing cursor. It returns the MomentaMouse instance.
  • setAllowCursorSwitching — Sets whether the MomentaMouse instance is allowed to switch cursors on pointerdown and pointerup events. It returns the MomentaMouse instance.
    • allowCursorSwitching — true — A Boolean that determines the cursor-switching function of the MomentaMouse instance. If set to true, the instance will switch the cursor to the grabbing cursor on pointerdown events and switch the cursor to the grab cursor on pointerup events. If set to false, the instance will not switch cursors. Switching cursors triggers reflow, which may cause performance issues.

  • setAllowHorizontalScrolling — Sets whether the MomentaMouse instance is allowed to scroll horizontally. It returns the MomentaMouse instance.
    • allowHorizontalScrolling — true — A Boolean that determines the scrollability of a MomentaMouse instance's horizontal axis. If set to true, the instance will be able to perform momentum scrolls on the vertical axis if the vertical axis is scrollable. If set to false, the instance will not be able to perform scrolls on the vertical axis.

  • setAllowVerticalScrolling — Sets whether the MomentaMouse instance is allowed to scroll vertically. It returns the MomentaMouse instance.
    • allowVerticalScrolling — true — A Boolean that determines the scrollability of a MomentaMouse instance's vertical axis. If set to true, the instance will be able to perform momentum scrolls on the horizontal axis if the horizontal axis is scrollable. If set to false, the instance will not be able to perform scrolls on the horizontal axis.

  • activate — Allows the MomentaMouse instance to perform momentum scrolls. To function properly, it changes the CSS cursor, disallows text selection, and disallows dragging. It returns the MomentaMouse instance.

  • deactivate — Blocks the MomentaMouse instance from performing momentum scrolls. It reverts the CSS cursor, allows text selection, and allows dragging. It returns the MomentaMouse instance.

  • toggleActivation — Toggles the MomentaMouse instance's activation state. It returns the MomentaMouse instance.

Events

Below is a list of all CustomEvents dispatched by MomentaMouse. You can listen for them with the addEventListener method.

Event names are bolded and are followed by a description of the trigger that leads to their dispatch.

If an event includes custom properties in the CustomEvent details object, they are listed below the event description. Custom property names are italicized and are followed by a description.

Static Events:

  • momentaMouseScrollerPointerRoute — Dispatches when MomentaMouse selects an EventTarget to be the handler of PointerEvents. The EventTarget may be the scroll container of a MomentaMouse instance, or may match one of the selectors in the selectorsOfClickableElements or selectorsOfOtherTouchScrollers lists.
    • pointerEvent — A PointerEvent, which is meant for processing by the routeTo EventTarget. If there are no nested EventTargets of interest, it is simply a pointerdown event. If there are nested EventTargets of interest and a threshold test is performed, it will be a pointermove event, which provides the last known coordinates of the pointer so that the routeTo EventTarget can smoothly transition into handling the event.
    • routeTo — The EventTarget that MomentaMouse selected to be the handler of PointerEvents.
    • routeFrom — The EventTarget which had previously been selected by MomentaMouse to be the handler of PointerEvents before a threshold test was performed, but is now giving up its handling of PointerEvents to the new routeTo EventTarget after completion of a threshold test.

Instance Events:

  • momentaMouseScrollerActivate — Dispatches when a MomentaMouse instance is activated
    • scrollContainer — The MomentaMouse instance's scroll container
    • reason — The reason for the change in activation

  • momentaMouseScrollerDeactivate — Dispatches when a MomentaMouse instance is deactivated
    • Same as momentaMouseScrollerActivate

  • momentaMouseScrollerPointerHandlingStart — Dispatches when a MomentaMouse instance gets control of the pointer
    • scrollContainer — The MomentaMouse instance's scroll container

  • momentaMouseScrollerPointerHandlingStop — Dispatches when a MomentaMouse instance loses control of the pointer
    • scrollContainer — The MomentaMouse instance's scroll container
    • interruptedBy — The cause of a pointer handling's interruption if it was interrupted; Otherwise, null

  • momentaMouseScrollerScrollStart — Dispatches at the beginning of a momentum scroll
    • scrollContainer — The MomentaMouse instance's scroll container
    • initialVelocityX — The initial pointer velocity on the x axis
    • initialVelocityY — The initial pointer velocity on the y axis
    • initialVelocity — The hypotenuse of the initial pointer velocities
    • startPoint — The pointer's starting coordinates
    • endPoint — The pointer's ending coordinates
    • distance — The distance scrolled after the pointerup event
    • elapsedTime — The elapsed time of the scroll
    • interruptedBy — The cause of a scroll's interruption if it was interrupted; Otherwise, null

  • momentaMouseScrollerScroll — Dispatches continuously while momentum scrolling
    • Same as momentaMouseScrollerScrollStart

  • momentaMouseScrollerScrollStop — Dispatches at the end of a momentum scroll
    • Same as momentaMouseScrollerScrollStart

  • momentaMouseScrollerBounceStart — Dispatches at the beginning of a bounce
    • scrollContainer — The MomentaMouse instance's scroll container
    • startTimeX — The timestamp at the moment the momentum scroll impacted a border on the x axis
    • startTimeY — The timestamp at the moment the momentum scroll impacted a border on the y axis
    • initialVelocityX — The velocity of the momentum scroll at the moment it impacted a border on the x axis
    • initialVelocityY — The velocity of the momentum scroll at the moment it impacted a border on the y axis
    • elapsedTimeX — The elapsed time of the bounce that occurred on the x axis
    • elapsedTimeY — The elapsed time of the bounce that occurred on the y axis
    • interruptedBy — The cause of a bounce's interruption if it was interrupted; Otherwise, null

  • momentaMouseScrollerBounceStop — Dispatches when a bounce stops
    • Same as momentaMouseScrollerBounceStart