Flow-Scroll

Smooth, effortless, and automated page scrolling with multiple approaches to controlling the speed, direction, distance, and duration of each scroll effect.

Can be downloaded via npm using: > npm install flow-scroll

API Methods

flow.x(pixels, [duration])

Scroll the page along its x-axis by the specified number of pixels, over a given duration of time.

• pixels : The number of pixels on the x-axis of the page (left and right) you would like to scroll. Positive numbers scroll right on the page; negative numbers scroll left.

• duration : How long (in seconds) you would like your scroll effect to last.
  Default: If omitted, negative, or zero, default scroll speed of 2000px/second will be used in place of a specific duration.

flow.y(pixels, [duration])

Scroll the page along its y-axis by the specified number of pixels, over a given duration of time.

• pixels : The number of pixels on the y-axis of the page (up and down) you would like to scroll. Positive numbers scroll down the page; negative numbers scroll up.

• duration : How long (in seconds) you would like your scroll effect to last.
  Default: If omitted, negative, or zero, default scroll speed of 2000px/second will be used in place of a specific duration.

flow.xy(pixelsX, [pixelsY], [duration])

Scroll the page along its x- and y-axes by the specified numbers of pixels, over a given duration of time.

• pixelsX : The number of pixels on the x-axis of the page (left and right) you would like to scroll. Positive numbers scroll right on the page; negative numbers scroll left.

• pixelsY : The number of pixels on the y-axis of the page (up and down) you would like to scroll. Positive numbers scroll down the page; negative numbers scroll up
  Default: If omitted, value will be set to match 'x' value (use flow.x() if you wish to only scroll on the x-axis).

• duration : How long (in seconds) you would like your scroll effect to last.
  Default: If omitted, negative, or zero, default scroll speed of 2000px/second will be used in place of a specific duration.

flow.toX(x, [duration])

Scroll the page to a specific, pixel-based, x-coordinate over a given duration of time.

• x : The specific x-coordinate (in pixels) to which you would like the page to be scrolled. If value is higher than the maximum scrollable area on the x-axis (or lower than the minimum), the page will be scrolled to that maximum (or minimum) value and no further.

• duration : How long (in seconds) you would like your scroll effect to last.
  Default: If omitted, negative, or zero, default scroll speed of 2000px/second will be used in place of a specific duration.

flow.toY(y, [duration])

Scroll the page to a specific, pixel-based, y-coordinate over a given duration of time.

• y : The specific y-coordinate (in pixels) to which you would like the page to be scrolled. If value is higher than the maximum scrollable area on the y-axis (or lower than the minimum), the page will be scrolled to that maximum (or minimum) value and no further.

• duration : How long (in seconds) you would like your scroll effect to last.
  Default: If omitted, negative, or zero, default scroll speed of 2000px/second will be used in place of a specific duration.

flow.toXY(x, [y], [duration])

Scroll the page to a specific, pixel-based, x/y coordinate pair over a given duration of time.

• x : The specific x-coordinate (in pixels) to which you would like the page to be scrolled. If value is higher than the maximum scrollable area on the x-axis (or lower than the minimum), the page will be scrolled to that maximum (or minimum) value and no further.

• y (optional): The specific y-coordinate (in pixels) to which you would like the page to be scrolled. If value is higher than the maximum scrollable area on the y-axis (or lower than the minimum), the page will be scrolled to that maximum (or minimum) value and no further.
  Default: If omitted, value will be set to match 'x' value.

• duration : How long (in seconds) you would like your scroll effect to last.
  Default: If omitted, negative, or zero, default scroll speed of 2000px/second will be used in place of a specific duration.

flow.toTop()

Scroll to the top of the page, moving at the default scroll speed (2000px/second as starting value). This default speed can be configured. See the configuration section below for specifics.

flow.toBottom()

Scroll to the bottom of the page, moving at the default scroll speed (2000px/second as starting value). This default speed can be configured. See the configuration section below for specifics.

flow.toElem(elem, [duration])

Use an element on a page as an anchor point and scroll the page to that specific location over a given duration of time.

• elem : The element you wish to use as an anchor for setting the scroll destination point.

• duration (optional) : How long (in seconds) you would like your scroll effect to last.
  Default: If omitted, negative, or zero, default scroll speed of 2000px/second will be used in place of a specific duration.

API Configuration Properties

flow.defaultRate

Gets or sets the default scroll speed for API method calls made without a duration value. Measured in terms of pixels per second.
Default : 2000

flow.timeBased

Gets and sets whether current API method calls read the duration in terms of a seconds-based time value or a per-frame rate to be used until the desired scroll distance has been covered.
Default: true

NOTE: When set to false, the duration value is read as indicating how many pixels you wish the page to scroll on every call to requestAnimationFrame (which is called approximately 60 times per second during each scroll event). This is an advanced feature, included for those requiring more fine grained control over the speed and timing of page scrolling behavior.

For those who wish to use this feature, it is useful to know the specific conversion rates for setting and using per-frame scrolling values. Per-frame scrolling rates can be converted to per-second scrolling rates by multiplying the per-frame value by 60 (per-frame rate * 60 = per-second rate). Likewise, dividing the per-second scrolling rate by 60 will give you the approximate per-frame scrolling rate (per-second rate / 60 = per-frame rate).

For example, the default per-second scroll rate for Flow-Scroll is 2000 pixels per second. This means the per-frame rate is: 2000px / 60 = ~33.3px per frame.

FAQs

What happens if I call a method with a scroll value larger than the available scrollable area on a page?

Flow-Scroll will only scroll as far as the space available on a page. If the value provided is larger than the available scrollable area, Flow-Scroll will simply stop at the end of that scrollable space (i.e new scrollable space will not be created on the page to continue scrolling).

How are 'x' and 'y' coordinates measured on the page?

The 'x' and 'y' coordinates of each method call are measured in relation to the top-left corner of the browser window; with the absolute reference point for all scrolling events being the top-left (0 offset-left and 0 offset-top) corner of the actual page/HTML document itself.

For example, an element with position set to absolute, document 'body' as its offset parent, and both the left and top style properties set to '0px' would be placed at this absolute (0, 0) reference point. Calling flow.toXY(0,0) would place this element's own top-left corner in the top-left corner of the browser window.