Table of Contents generated with DocToc
Adds scroll-and-snap behaviour to any element that has a vertical scrollbar:
<div style="height: 200px;" snapscroll="">
<div style="height: 200px;"></div>
<div style="height: 200px;"></div>
<div style="height: 200px;"></div>
</div>You can disable snapscroll programmatically by passing false or a binding that
evaluates to false:
angular.controller('MainCtrl', function ($scope, $window) {
$scope.snapscrollEnabled = $window.innerWidth > 320;
}); <!-- always disabled -->
<div style="height: 200px;" snapscroll="false"> ... </div>
<!-- disabled programmatically -->
<div ng-controller="MainCtrl">
<div snapscroll="snapscrollEnabled"> ... </div>
</div>Other attributes that can be added are:
provides a two-way bind to the current index of the visible child element. indeces are zero-based.
<!-- setting an initial snapIndex to automatically seek to on page load -->
<div snapscroll="" snap-index="1"> ... </div><div ng-init="snapIndex=0">
<button ng-click="snapIndex=1">Go to index 1</button>
<div snapscroll="" snap-index="snapIndex"> ... </div>
</div>allows you to provide the height of the element (and children elements) instead of doing it in CSS. this is a two-way bind.
<div snapscroll="" snap-height="200"> ... </div><div ng-init="snapHeight=200">
<div snapscroll="" snap-height="snapHeight"> ... </div>
</div>instead of snap-height, you can use this attribute (it's actually a directive)
to make the snapHeight equal the window height. snapHeight will be updated
automatically if the window is resized.
<div snapscroll="" fit-window-height=""> ... </div>enable support for snapping up and down when the up and down keyboard keys are pressed, respectively.
<div snapscroll="" enable-arrow-keys=""> ... </div>by default, wheel (and trackpad) events will lead to the element being snapped up or down. you can disable this functionality using this attribute, which means that wheel events will lead to the element being scrolled normally instead of being snap-scrolled.
<div snapscroll="" disable-wheel-binding=""> ... </div>note that you will still be able to control snapping using the
snap-index binding and using the keyboard arrow keys if
enable-arrow-keys is set.
also note that when the element is scrolled normally, snapscroll will try to
reset the scrollTop so that the current snap is fully visible. So to ensure
wheel events have completely no side-effects, also set the
prevent-snapping-after-manual-scroll
attribute.
snapscroll takes over the wheel events for the element it's bound to and
translates them to snapping up/down. to allow the normal scrolling on a nested
element (i.e. prevent snapping when the wheel event comes from that element),
add a class to the element and provide that class-name as the value for the
ignore-wheel-class attribute.
<div snapscroll="" enable-arrow-keys="" ignore-wheel-class="ignore-me">
<div>
<div class="ignore-me">normal scrolling here</div>
</div>
</div>note that if you wish to ignore wheel events from an element with children, then the class-name must also be added to the child elements. that's because in this case wheel events will bubble from the child elements.
is a callback executed before snapping occurs. the callback is passed a
snapIndex parameter, which is the index being snapped to, and an $event
parameter, which is the event triggering the snapping, if available (e.g.
WheelEvent if it was the mousewheel or KeyboardEvent if it was an arrow key).
returning false from this callback will prevent snapping. you can also override
the next snapIndex by returning a number.
angular.controller('MainCtrl', function ($scope) {
$scope.beforeSnap = function (snapIndex) {
console.log('snapping to', snapIndex);
if (snapIndex > 4) {
return false; // prevent snapping
}
if (snapIndex === 2) {
return 3; // snap to snapIndex 3 instead
}
};
});<div ng-controller="MainCtrl">
<div snapscroll="" before-snap="beforeSnap(snapIndex)"> ... </div>
</div>is a callback executed after snapping occurs. the callback is passed a
snapIndex parameter, which is the index just snapped to, and an $event
parameter, which is the event triggering the snapping if available ( e.g.
WheelEvent if it was the mousewheel or KeyboardEvent if it was an arrow key). any return value from
this callback is ignored.
angular.controller('MainCtrl', function ($scope) {
$scope.log = function (snapIndex) {
console.log('just snapped to', snapIndex);
};
});<div ng-controller="MainCtrl">
<div snapscroll="" after-snap="log(snapIndex)"> ... </div>
</div>allows turning the snap animation on/off. this is a two-way bind.
angular.controller('MainCtrl', function ($scope) {
$scope.index = 1;
$scope.animation = false;
$scope.enableAnimation = function () {
if (!$scope.animation) {
$scope.animation = true;
}
};
});<!-- prevent animation for the initial snap on page load -->
<div ng-controller="MainCtrl">
<div snapscroll="" snap-index="index" snap-animation="animation"
after-snap="enableAnimation()">
...
</div>
</div>integer value indicating the length of the snap animation in milliseconds. a value of 0 disables the snap-animation as well. default is 800ms.
<div snapscroll="" snap-duration="1200"> ... </div>the snap-duration can also be changed for all snapscroll instances by changing the default value:
angular.module('myapp', ['snapscroll'])
.value('defaultSnapscrollSnapDuration', 1200);function reference that allows overriding the default easing of the snap animation. note that this is not a regular angular callback but rather a function reference. the default easing is easeInOutQuad. any of the javascript easing functions can be provided.
angular.controller('MainCtrl', function ($scope) {
$scope.linearEasing = function () {
// easing code
};
});<div ng-controller="MainCtrl">
<div snapscroll="" snap-easing="linearEasing"> ... </div>
</div>the snap-easing can also be changed for all snapscroll instances by changing the default value:
angular.module('myapp', ['snapscroll'])
.value('defaultSnapscrollScrollEasing', function () {
// ... easing code
});snapscroll listens to the scroll event on the element that it's bound to and
automatically resets the current snap after a manual scroll so that it's always
fully visible. this behaviour can be prevented by adding this attribute.
the scroll listener described above is throttled using a scroll-delay. this
delay can be changed by providing a value in milliseconds. it can also be turned
off by providing false.
<div snapscroll="" scroll-delay="400"> ... </div>the scroll-delay can also be changed for all snapscroll instances by changing the default value:
angular.module('myapp', ['snapscroll'])
.value('defaultSnapscrollScrollDelay', 400);the resize listener used by fit-window-height is throttled using a
resize-delay. this delay can be changed by providing a value in milliseconds.
it can also be turned off by providing false.
<div snapscroll="" fit-window-height="" resize-delay="400"> ... </div>the scroll-delay can also be changed for all snapscroll instances by changing the default value:
angular.module('myapp', ['snapscroll'])
.value('defaultSnapscrollResizeDelay', 400);In order to prevent snapping twice in the same direction on trackpads with high
sensitivity, there is a 1 second delay that disables snapping to the same
direction. This can be altered using this attribute or disabled altogether by
passing false.
<div snapscroll="" prevent-double-snap-delay="400"> ... </div>the scroll-delay can also be changed for all snapscroll instances by changing the default value:
angular.module('myapp', ['snapscroll'])
.value('defaultSnapscrollPreventDoubleSnapDelay', 400);