jQuery Scroll Lock Plugin

Locks mouse wheel scroll inside container, preventing it from propagating to parent elements

Project maintained by Mohammad Younes Hosted on GitHub Pages — Theme by mattgraham

Scroll Lock

Scroll Lock is a jQuery plugin that fully addresses the issue of locking mouse wheel scroll inside a given container, preventing it from propagating to parent element.

Features

Install with NuGet 


Install-Package jquery-scrollLock

Install with Bower 


bower install jquery-scrollLock

Install with NPM 


npm install jquery-scroll-lock --save

Demo

Example 1

Locking a scrollable element prevents wheel scroll event from propagating to its parent element.

Scroll over this using mouse wheel.

This plugin does not provide any CSS, you need to implement your own!

Scroll over this using mouse wheel.

This plugin does not provide any CSS, you need to implement your own!

Scroll over this using mouse wheel.

This plugin does not provide any CSS, you need to implement your own!

Scroll over this using mouse wheel.

This plugin does not provide any CSS, you need to implement your own!

Scroll over this using mouse wheel.

This plugin does not provide any CSS, you need to implement your own!

Scroll over this using mouse wheel.

This plugin does not provide any CSS, you need to implement your own!
Scrollable Content

Example 2

Even none-scrollable elements can be locked.

In strict mode, this element will not lock as it has no vertical scrollbar.
None Scrollable Content

Usage

Trigger Scroll Lock via JavaScript:


$('#target').scrollLock();

Trigger Scroll Lock via Markup:


<!-- HTML -->
<div data-scrollLock 
     data-strict='true'
     data-selector='.child' 
     data-animation='{"top":"top locked","bottom":"bottom locked"}'
     data-keyboard='{"tabindex":0}' 
     data-unblock='.inner' >
 … 
</div>

<!-- JavaScript -->
$('[data-scrollLock]').scrollLock()

Options

Option Type Default Description
animation object false An object defining CSS class(es) to be applied when top or bottom edge is locked. (see remarks1)
keyboard object false When enabled, keys that causes scrolling will also be locked. (see remarks2)
selector string false When provided, matching descendants will be locked. Useful when dealing with dynamic HTML.
strict boolean false When enabled, only elements passing the strictFn check will be locked.
strictFn function remarks3 This function is responsible for deciding if the element should be locked or not.
touch boolean auto Indicates if an element's lock is enabled on touch screens.
unblock string false When provided, matching descendants scrolling will be unblocked. Useful when having a scrollable element inside a locked one.

Remarks1

This is pure JavaScript plugin, it does not provide any CSS. You need to implement your own!

The `animation` option has two keys: 

{
  "top": "top locked",
  "bottom": "bottom locked"
}

When an edge is locked, the value of both animation.top + animation.bottom will be removed from the locked element's class list

Then based on the locked edge, the value of animation.top or animation.bottom is added to the class list, and removed once the animationend event is fired.

Remarks2

In chrome, The following keys causes a scroll, which may propagate to parent element.

space, pageup, pagedown , end , home, up, down

The `keyboard` option has one key: 

{ "tabindex": 0 }

The `tabindex` is required to be able to listen to keyboard events on none input elements, such as a `div`. The side effect of adding a `tabindex` is the browser highlight when the element is focused.

Which can be avoided via CSS `outline` property. 

.scrollable{ outline:0; }

Remarks3

The default `strictFn` implementation checks if the element requires a vertical scrollbar.


strictFn = function($element){
  return $element.prop('scrollHeight') > $element.prop('clientHeight'); 
}

In previous versions ( ≤ v2.1.0 ), The check was based on scrollbar visibility, In case you require such behavior, include the following in your script: 


$.fn.scrollLock.defaults.strictFn = function ($element) {
  var clientWidth = $element.prop('clientWidth'),
  offsetWidth = $element.prop('offsetWidth'),
  borderRightWidth = parseInt($element.css('border-right-width'), 10),
  borderLeftWidth = parseInt($element.css('border-left-width'), 10)
  return clientWidth + borderLeftWidth + borderRightWidth < offsetWidth
}

Methods

Method Description
.scrollLock('enable') Enables an element's Scroll Lock.
.scrollLock('disable') Disables an element's Scroll Lock.
.scrollLock('toggleStrict') Toggles an element's strict option.
.scrollLock('destroy') Disables and destroys an element's Scroll Lock.

Events

Event Description
top.scrollLock This event fires immediately when the top edge scroll is locked.
bottom.scrollLock This event fires immediately when the bottom edge scroll is locked. 

$('#target').on('top.scrollLock', function (evt) {
  // do magic :)
})

Have a suggestion or a bug ? please open a new issue.