https://github.com/offthehandle/jquery-smoothscroll
Smooth Scroll is a jQuery utility that provides animated bookmark, sticky box and page top links.
https://github.com/offthehandle/jquery-smoothscroll
bookmark jquery jquery-plugin smooth-scrolling sticky
Last synced: 16 days ago
JSON representation
Smooth Scroll is a jQuery utility that provides animated bookmark, sticky box and page top links.
- Host: GitHub
- URL: https://github.com/offthehandle/jquery-smoothscroll
- Owner: offthehandle
- License: mit
- Created: 2014-12-18T04:02:49.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2018-05-19T02:04:27.000Z (about 7 years ago)
- Last Synced: 2023-12-16T04:20:47.988Z (over 1 year ago)
- Topics: bookmark, jquery, jquery-plugin, smooth-scrolling, sticky
- Language: JavaScript
- Homepage: http://www.adamdelucia.com/docs/project/smooth-scroll
- Size: 29.3 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
### Quick links
- [jQuery Smooth Scroll](#jquery-smooth-scroll)
- [Installation](#installation)
- [Install with NuGet](#install-with-nuget)
- [Features](#features)
- [Turning Features On](#turning-features-on)
- [Enable or Disable Features Example](#enable-or-disable-features-example)
- [Options](#options)
- [Common Options](#common-options)
- [Duration](#duration)
- [Callbacks](#callbacks)
- [Bookmark Options](#bookmark-options)
- [Container](#container)
- [Containers Array](#containers-array)
- [Link and Exclude](#link-and-exclude)
- [Exclude Example](#exclude-example)
- [Link Example](#link-example)
- [Exclude Within](#exclude-within)
- [Exclude Within Example](#exclude-within-example)
- [Offset Top](#offset-top)
- [Offset Top Example](#offset-top-example)
- [Bookmark Callbacks](#bookmark-callbacks)
- [Page Top Options](#page-top-options)
- [Page Top Class](#page-top-class)
- [Page Top Callbacks](#page-top-callbacks)
- [Sticky Box Options](#sticky-box-options)
- [Sticky Box Id](#sticky-box-id)
- [Sticky Box Image Url](#sticky-box-image-url)
- [Sticky Box Threshold](#sticky-box-threshold)
- [Sticky Box Callbacks](#sticky-box-callbacks)
- [Sticky Box Setup](#sticky-box-setup)
- [Sticky Box On Resize](#sticky-box-on-resize)
- [Sticky Box On Resize Example](#sticky-box-on-resize-example)
- [Sticky Box Resize Timeout](#sticky-box-resize-timeout)
# jQuery Smooth Scroll
Smooth Scroll is a jQuery utility. Its [3 features listed below](#features) can be configured and turned on or off as you like.
## Installation
Installation is easy and takes only a small amount of configuration. The only dependency is jQuery 1.9.1 or later. The default configuration activates bookmarks on all page links. See below for a basic configuration.
```javascript
$(document).ready(function () {
$.smoothScroll({
link: '.smooth-scroll'
});
});
```
This configuration will enable bookmarks with the default options on any link decorated with the `smooth-scroll` class.
##### Install with NuGet
To install Smooth Scroll, run the following command in the Package Manager Console:
```
PM> Install-Package jQuery.SmoothScroll
```
## Features
1. Bookmarks
2. To page top links
3. End of page link
Each of the 3 features of Smooth Scroll can be turned on or off. You can use a single feature, different combinations of features or use all 3 features together.
### Turning Features On
The only feature turned on by default is bookmarks. Each feature has a property that accepts a boolean value - `true` or `false` - to turn the feature on or off.
##### Enable or Disable Features Example
```javascript
$(document).ready(function () {
$.smoothScroll({
bookmarks: true | false,
pageTopLink: true | false,
stickyBox: true | false,
});
});
```
## Options
See below for the complete configuration with default settings.
```javascript
bookmarks: true,
container: 'html, body',
containersArray: [],
link: 'a',
duration: 400,
exclude: [],
excludeWithin: [],
beforeScroll: null,
afterScroll: null,
stickyBox: false,
stickyBoxId: 'scroll-to-top',
stickyBoxImageUrl: '/Content/images/smooth_scroll_arrow.png',
stickyBoxThreshold: 50,
stickyBoxDuration: 400,
stickyBoxSetup: null,
stickyBoxBeforeScroll: null,
stickyBoxAfterScroll: null,
stickyBoxOnResize: null,
stickyBoxResizeTimeout: 250,
pageTopLink: false,
pageTopClass: 'page-top',
pageTopDuration: 400,
pageTopBeforeScroll: null,
pageTopAfterScroll: null,
offsetTop: 0
```
### Common Options
All 3 features have common options like duration and callbacks. These common options are independently configurable for each feature.
#### Duration
The `duration`, `pageTopDuration` and `stickyBoxDuration` options specify the scroll speed.
#### Callbacks
Each feature has callbacks that allow you to set JavaScript functions to be executed each time a specific action takes place within the utility. All features execute functions before and after each Smooth Scroll. You can find callbacks for specific features below.
* Bookmarks: `beforeScroll`, `afterScroll`
* Page Top: `pageTopBeforeScroll`, `pageTopAfterScroll`
* Sticky Box: `stickyBoxSetup`, `stickyBoxOnResize`
### Bookmark Options
* With Defaults
```javascript
bookmarks: true,
container: 'html, body',
containersArray: [],
link: 'a',
duration: 400,
exclude: [],
excludeWithin: [],
beforeScroll: null,
afterScroll: null,
offsetTop: 0
```
#### Container
The `container` option sets a CSS selector within which to look for all bookmark links.
#### Containers Array
The `containersArray` option allows an array of strings to be set for multiple containers. When the `container` or `containersArray` option is set, even a match to the `link` selector will not be activated if it is not found inside the container(s).
#### Link and Exclude
The `link` option specifies selectors that should have Smooth Scroll bookmarks enabled. When you enable `link` on generic elements - like `a` - you can exclude a subset of links that should not be Smooth Scroll enabled using the `exclude` option. See the use cases below.
* Exclude offsite links in a nav element
##### Exclude Example
###### HTML
```html
```
###### Smooth Scroll Options
```javascript
$(document).ready(function () {
$.smoothScroll({
container: 'nav',
exclude: ['.disable-smooth-scroll']
});
});
```
Another option is to create an opt-in class. Smooth Scroll simply provides options to suit your preference with the most efficient flow in mind for your project.
##### Link Example
###### HTML
```html
```
###### Smooth Scroll Options
```javascript
$(document).ready(function () {
$.smoothScroll({
container: 'nav',
link: '.smooth-scroll'
});
});
```
#### Exclude Within
The `excludeWithin` option specifies an inner container of `containersArray` or `container` within which no bookmarks should be enabled. Below is a use case for this option.
##### Exclude Within Example
###### HTML
```html
```
###### Smooth Scroll Options
```javascript
$(document).ready(function () {
$.smoothScroll({
container: '#nav',
excludeWithin: '.dropdown'
});
});
```
#### Offset Top
The `offsetTop` option is used to adjust the scroll position for fixed navbars. Set this option to the height of your fixed navbar to keep the top of bookmarked content visible on scroll, otherwise it will be hidden behind the navbar.
###### Offset Top Example
```javascript
$(document).ready(function () {
$.smoothScroll({
offsetTop: 50
});
});
```
#### Bookmark Callbacks
The callbacks have 1 argument: `loc`, the href value of the element that triggered the scroll. The callbacks have `this` set to the specific jQuery Object that triggered the scroll.
### Page Top Options
The page top feature is used to trigger a scroll to page top from anywhere on the page.
* With Defaults
```javascript
pageTopLink: false,
pageTopClass: 'page-top',
pageTopDuration: 400,
pageTopBeforeScroll: null,
pageTopAfterScroll: null,
```
#### Page Top Class
The `pageTopClass` specifies the class name that will be used to trigger a scroll to page top. The `.` is not required before the value since it must be a class name.
#### Page Top Callbacks
The callbacks have `this` set to the specific jQuery Object that triggered the scroll.
### Sticky Box Options
The top widget is used to scroll back to page top and appears after the user has reached the bottom of the page, making it available when needed. It is created programmatically and provides some options to configure its setup.
* With Defaults
```javascript
stickyBox: false,
stickyBoxId: 'scroll-to-top',
stickyBoxImageUrl: '/Content/images/smooth_scroll_arrow.png',
stickyBoxThreshold: 50,
stickyBoxDuration: 400,
stickyBoxSetup: null,
stickyBoxBeforeScroll: null,
stickyBoxAfterScroll: null,
stickyBoxOnResize: null,
stickyBoxResizeTimeout: 250,
```
#### Sticky Box Id
The `stickyBoxId` specifies the id of the top widget element. The `#` is not required before the value since it is an id.
#### Sticky Box Image Url
The `stickyBoxImageUrl` specifies the path of the image to use as the scroll top arrow. An image is provided. If you use an image with a different name or location, update this option.
#### Sticky Box Threshold
The `stickyBoxThreshold` specifies the number of pixels the scroll position is from the bottom of the page when the widget appears.
#### Sticky Box Callbacks
##### Sticky Box Setup
The `stickyBoxSetup` is a callback. It fires on page start after the widget is created. The value of `this` is set to the jQuery Object of the top widget by its CSS id; e.g. `$('#scroll-to-top')`.
##### Sticky Box On Resize
The `stickyBoxOnResize` is a callback. It fires on page resize to provide a hook for positioning the top widget. The value of `this` is set to the jQuery Object of the top widget by its CSS id; e.g. `$('#scroll-to-top')`.
###### Sticky Box On Resize Example
```javascript
$(document).ready(function () {
$.smoothScroll({
stickyBoxOnResize: function () {
this.css('right', $('.container').offset().left + 15 + 'px');
}
});
});
```
##### Sticky Box Resize Timeout
The `stickyBoxResizeTimeout` is the duration of the timeout to optimize the `stickyBoxOnResize` callback. You can delay the execution of the callback to allow other resize events to complete by setting this value higher. Setting it to 0 will execute the callback immediately.