rocknrollmarc / angular-snapscroll

Vertical scroll-and-snap functionality in angular

angular-snapscroll

angular-snapscroll adds vertical scroll-and-snap functionality to angular. Demo

• JS-only implementation
• Only requires angular core
• 5.7kB when minified, 2.1kB when gzipped

Installation

Install with bower:

bower install angular-snapscroll

Or simply download the latest release.

Usage

Include the main JS file in your HTML. For example:

<!-- if you installed it with bower: -->
<script src="/bower_components/angular-snapscroll/dist/angular-snapscroll.min.js"></script>
<!-- or if you downloaded a release archive: -->
<script src="/dist/angular-snapscroll.min.js"></script>

Add snapscroll to your app's module dependencies:

angular.module('myapp', ['snapscroll']);

And now you can add a snapscroll attribute to any element to make it snap-scrollable! The element would have a scrollbar to begin with, the idea being that with the snapscroll attribute you're adding scroll-and-snap behaviour to an element that is otherwise already scrollable:

<div style="height: 200px;" snapscroll="">
    <div></div>
    <div></div>
    <div></div>
</div>

All you need to set is the height of the element and the directive will take care of the rest. Or to have the element fill the browser viewport height:

<div snapscroll="" fit-window-height="">
    <div></div>
    <div></div>
    <div></div>
</div>

Touch support

I recommend using angular-swipe to add touch support but you can use any other library or module that recognizes vertical swipe gestures (e.g. hammer.js). Here's how to do it using angular-swipe:

<div style="height: 200px;" ng-init="snapIndex=0" snapscroll="" snap-index="snapIndex" ng-swipe-up="snapIndex=snapIndex+1" ng-swipe-down="snapIndex=snapIndex-1">
    <div></div>
    <div></div>
    <div></div>
</div>

If you have nested snapscroll instances, remember to prevent the swipe events in a nested instance from bubbing up to the parents. See the demo for an example (the demo uses angular-swipe).

Documentation

Have a look at the docs for all the configuration options. For more examples, view the source on the demo site.

Known issue and workaround

Swiping on a trackpad with high sensitivity (i.e. on a Mac) may cause a snapscroll instance to snap twice in the same direction. The workaround for this is to set defaultSnapscrollSnapDuration or snap-duration to a higher value (try 1000ms or 1200ms).

Todo's

• snapscroll as an element - would allow use of templates and ngAnimate for animations. Currently this repo has a (rather outdated) 'as-element' branch for this.
• more browser tests

Contributing

Contributions are welcomed! Here are the contribution guidelines.

This project uses Grunt for automation. Once you've forked the repo and cloned it to your machine, run this to install all the dependencies:

npm install && bower install

Then to continuously watch files and run tests as you write code, run:

grunt

Check out the Gruntfile for more grunt tasks (grunt test, grunt build etc).

License

The MIT License