Aim of this library is to provide more user-friendly and less epileptic scrolling effect on a long content as well as unification of all types of scrolling on a page.
Aim of this library is to provide more user-friendly
and less epileptic scrolling effect on a long content
by creating a customized easing and to apply this easing
to all various types of scrolling on a page
(see [Covered scenarios](#Covered scenarios)).
## Installation and usage
## Installation
```bash
npm install @grifart/smoothscroll
# or
yarn add @grifart/smoothscroll
```
```javascript
importSmoothScrollfrom'@grifart/smoothscroll';
## Usage
// use defaults
SmoothScroll.enable();
`@grifart/smoothscroll` exposes various functions to handle
different types of scrolling in your application. Each function
is importable through standard ES `import` directive.
// customize
SmoothScroll.enable({
scrollOnLoad:true,
scrollOnLinkClick:true,
});
```
### Global scrolling behavior
| Function | Description |
|---|---|
| **`handleOnLoadScroll()`** | Attaches scrolling to anchored element when the page is loaded.\* |
| **`handleOnLinkClickScroll()`** | Attaches scrolling to given element when user clicks on an `a` tag having `href` starting with `#` character. |
| **`handleGlobalScrollingBehavior()`** | Calls all functions above. |
### Options
Use these functions **in top-level code**:
| Option | Value | Default value | Description |
| --- | --- | --- | --- |
| `scrollOnLoad`\* | `true`/`false` | `true` | Causes smooth scroll to anchored element when the page is loaded.
| `scrollOnLinkClick` | `true`/`false` | `true` | Causes smooth scroll on given element when user clicks on an `a` tag having `href` starting with `#` character.
\*Note: when the page load lasts more than 500 ms, load smooth scroll effect is disabled as it would lead to user-unfriendly behaviour like jumping on the page up and down due to browser native behaviour.
\*Note: when page load lasts more than 500 ms, load scroll effect
is disabled as it would lead to user-unfriendly behaviour like
jumping on the page up and down due to browser native behaviour.
### Methods
### scrollToX functions
|Method|Parameters|
|Function|Parameters|
|---|---|
|`enable([options])`|`options` (optional): see above|
|`scrollToElement(element[, onScrollFinishedCallback])`|`element`: element to scroll to `onScrollFinishedCallback` (optional): callback to trigger when scrolling is finished|
|`scrollToOffset(topOffset[, onScrollFinishedCallback])`|`topOffset`: scroll offset from top of document `onScrollFinishedCallback` (optional): callback to trigger when scrolling is finished|
|`scrollToTarget(hashTarget[, onScrollFinishedCallback])`|`hashTarget`: instance of `HashTarget` object\* or `string`\*\*`onScrollFinishedCallback` (optional): callback to trigger when scrolling is finished|
|`scrollToElement(element[, onScrollFinishedCallback])`|`element`: element to scroll to; `onScrollFinishedCallback` (optional): callback to trigger when scrolling is finished|
|`scrollToOffset(topOffset[, onScrollFinishedCallback])`|`topOffset`: scroll offset from top of document; `onScrollFinishedCallback` (optional): callback to trigger when scrolling is finished|
|`scrollToTarget(hashTarget[, onScrollFinishedCallback])`|`hashTarget`: instance of `HashTarget` object\* or `string`\*\*; `onScrollFinishedCallback` (optional): callback to trigger when scrolling is finished|
\*`HashTarget` is a value object representing a target to scroll to. You can easily initalize it with named constructor: `HashTarget.fromString('#some-identifier', document)`
\*\* In case of passing `string`, `HashTarget` object will be instantiated automatically with current `document` context.
\*`HashTarget` is a value object representing a target to scroll to.
You can easily initalize it with named constructor:
\*\* In case of passing `string`, `HashTarget` object will be
instantiated automatically with current `document` context.
## More about
### Custom scrolling effect
Improved scrolling effect (internally called `ease-in-skip-out`) is registered by default and it works as basic ease-in-out with one modification that it skips content if it is too long. This results in nicer transition between two parts of a page.
Improved scrolling effect (internally called `ease-in-skip-out`) is registered
by default and it works as basic ease-in-out with one modification
that it skips content if it is too long. This results in nicer transition
between two distant parts in a page.
### Covered scenarios
...
...
@@ -56,6 +71,7 @@ Improved scrolling effect (internally called `ease-in-skip-out`) is registered b
- scroll when programatically needed to scroll to:
- given position (top offset)
- given element
- given target (`id` attribute)
## Development
...
...
@@ -64,5 +80,6 @@ yarn install
yarn dev
```
Every piece of this library comes with its unit test sitting alongside the script. Whole library is covered by integration test sitting in `src` folder.
Every piece of this library comes with its unit test sitting alongside the script.
Whole library is covered by integration test sitting in `src` folder.
Note that you have to build assets first (`yarn build`) before running a test.
