- jQuery Smooth Scroll
- Installation
- Features
- Options
Smooth Scroll is a jQuery utility. Its 3 features listed below can be configured and turned on or off as you like.
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.
$(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.
To install Smooth Scroll, run the following command in the Package Manager Console:
PM> Install-Package jQuery.SmoothScroll
- Bookmarks
- To page top links
- 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.
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.
$(document).ready(function () {
$.smoothScroll({
bookmarks: true | false,
pageTopLink: true | false,
stickyBox: true | false,
});
});See below for the complete configuration with default settings.
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: 0All 3 features have common options like duration and callbacks. These common options are independently configurable for each feature.
The duration, pageTopDuration and stickyBoxDuration options specify the scroll speed.
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
- With Defaults
bookmarks: true,
container: 'html, body',
containersArray: [],
link: 'a',
duration: 400,
exclude: [],
excludeWithin: [],
beforeScroll: null,
afterScroll: null,
offsetTop: 0The container option sets a CSS selector within which to look for all bookmark links.
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).
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
<nav>
<ul>
<li><a href="/#section-1">Section 1</a></li>
<li><a href="/#section-2">Section 2</a></li>
<li><a class="disable-smooth-scroll" href="http://www.offsite-link.com" target="_blank">Offsite Page</a></li>
</ul>
</nav>$(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.
<nav>
<ul>
<li><a class="smooth-scroll" href="/#section-1">Section 1</a></li>
<li><a class="smooth-scroll" href="/#section-2">Section 2</a></li>
<li><a href="http://www.offsite-link.com" target="_blank">Offsite Page</a></li>
</ul>
</nav>$(document).ready(function () {
$.smoothScroll({
container: 'nav',
link: '.smooth-scroll'
});
});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.
<nav class="navbar navbar-default">
<div class="container-fluid">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#nav" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/">Brand</a>
</div>
<div class="collapse navbar-collapse" id="nav">
<ul class="nav navbar-nav">
<li><a href="/#section-1">Section 1</a></li>
<li><a href="/#section-2">Section 2</a></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">
Plan Options <span class="caret"></span>
</a>
<ul class="dropdown-menu">
<li><a href="/basic-plan.html">Basic Plan</a></li>
<li><a href="/pro-plan.html">Pro Plan</a></li>
<li><a href="/premium-plan.html">Premium Plan</a></li>
</ul>
</li>
</ul>
</div>
</div>
</nav>$(document).ready(function () {
$.smoothScroll({
container: '#nav',
excludeWithin: '.dropdown'
});
});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.
$(document).ready(function () {
$.smoothScroll({
offsetTop: 50
});
});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.
The page top feature is used to trigger a scroll to page top from anywhere on the page.
- With Defaults
pageTopLink: false,
pageTopClass: 'page-top',
pageTopDuration: 400,
pageTopBeforeScroll: null,
pageTopAfterScroll: null,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.
The callbacks have this set to the specific jQuery Object that triggered the scroll.
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
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,The stickyBoxId specifies the id of the top widget element. The # is not required before the value since it is an id.
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.
The stickyBoxThreshold specifies the number of pixels the scroll position is from the bottom of the page when the widget appears.
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').
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').
$(document).ready(function () {
$.smoothScroll({
stickyBoxOnResize: function () {
this.css('right', $('.container').offset().left + 15 + 'px');
}
});
});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.