smartscroll is a tiny (1126b minfied + gzipped) jQuery plugin that has these independent features:
- Section scrolling - Scrolljacking
- Auto-hash - Updates the URL hash based on current position on page
- Responsive - You can disable scrolljacking below a set breakpoint
It also supports:
- Varied Section Heights
- Hybrid Scrolling - Both normal and scrolljacking on the same page
- Compatible with scrollbar - Can use scrollbar as well as mousewheel
- Disabling permalink history
- Correctly detects scroll events for inertial scrolling, by integrating with lethargy as a soft dependency (which means it will work without it)
- There can only be one set of adjoining sections
Install lethargy, which is available as a Bower package, which you can install with bower install
.
Structure your HTML like so (default options included)
<body>
<div class="section-wrapper">
<div class="section" data-hash="section-hash-name"></div>
<div class="section" data-hash="section-hash-name"></div>
</div>
<script src="path/to/lethargy.min.js">
<script src="path/to/smartscroll.min.js">
<script>
var options = {
mode: "vp", // "vp", "set"
autoHash: true,
sectionScroll: true,
initialScroll: true,
keepHistory: false,
sectionWrapperSelector: ".section-wrapper",
sectionClass: "section",
animationSpeed: 300,
headerHash: "header",
breakpoint: null
};
$.smartscroll(options);
</script>
</body>
You may also want to link to
styles.css
, but all that does is to ensure thehtml
andbody
elements have no margins nor padding
You may also leave out lethargy, but smartscroll may not work as well with scroll devices that uses inertial scrolling. Performance with lethargy can be slower, but it will be improved with further development.
mode
- (String) Valid options are:vp
(Viewport) - The sections will be automatically sized to be the same as the viewportset
- Use the height and width set by CSS (use this for having different heights for different sections)
autoHash
- (Boolean) Whether the auto-hashing feature is enabledsectionScroll
- (Boolean) Whether the section-scrolling feature is enabledinitialScroll
- (Boolean) Whether smartscroll should scroll to the position specified by the hash on initial loadkeepHistory
- (Boolean) Whether scrolling through different sections will be recorded in the browser's historysectionWrapperSelector
- (String) The CSS selector for the block element which wraps around your sectionssectionClass
- (String) The class name applied to each sectionanimationSpeed
- (Integer) Time taken for the scroll animation, in milisecondsheaderHash
- (String) The hash for the section above the sections, must be non-empty to reliably ensure the page do not jump when updating the hash value across browsers (as#
means_top
)breakpoint
- (Integer) The width of the browser below which scrolljacking will be disabled
Currently, there are two features of smartscroll, and this is how it's implemented:
- Smooth scroll by section
The mousewheel
and DOMMouseScroll
(for Firefox) events are bound.
When such event is fired in vp
mode, smartscroll will find it's most prominent section (one which occupies most of the screen), and smoothly scroll to the section above or below it.
When the event is fired in set
mode, smartscroll will find which section occupies the middle of the screen, and smoothly scroll to the section above or below it.
When scrolling outside of the sections, normal scrolling resumes.
- Changing URL hash based on the current section
The scroll
event is bound.
When the event is fired in vp
mode, smartscroll will see which section occupies the top of the viewport, and if the hash is different, replace it with the new one.
When the event is fired in set
mode, smartscroll will see which section occupies the middle of the viewport, and if the hash is different, replace it with the new one.
The following features may be implemented. Please register interest by opening/commenting on an issue.
- Touch support
- Horizontal scrolling