Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mohammadyounes/jquery-scrolllock

Locks mouse wheel scroll inside container, preventing it from propagating to parent element
https://github.com/mohammadyounes/jquery-scrolllock

jquery jquery-plugin jquery-scrolllock mousewheel scroll scroll-events scroll-lock scroll-plugins scrolling

Last synced: 3 days ago
JSON representation

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

Host: GitHub
URL: https://github.com/mohammadyounes/jquery-scrolllock
Owner: MohammadYounes
License: gpl-3.0
Created: 2014-03-28T14:17:48.000Z (over 10 years ago)
Default Branch: master
Last Pushed: 2017-06-16T21:28:39.000Z (over 7 years ago)
Last Synced: 2024-10-27T19:54:29.650Z (16 days ago)
Topics: jquery, jquery-plugin, jquery-scrolllock, mousewheel, scroll, scroll-events, scroll-lock, scroll-plugins, scrolling
Language: JavaScript
Homepage: http://mohammadyounes.github.io/jquery-scrollLock/
Size: 627 KB
Stars: 107
Watchers: 7
Forks: 27
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        [![GitHub version](https://badge.fury.io/gh/MohammadYounes%2Fjquery-scrollLock.svg)](http://badge.fury.io/gh/MohammadYounes%2Fjquery-scrollLock)

[![Bower version](https://img.shields.io/bower/v/jquery-scrollLock.svg)](https://github.com/MohammadYounes/jquery-scrollLock)

[![NuGet version](https://img.shields.io/nuget/v/jquery-scrollLock.svg)](https://www.nuget.org/packages/jquery-scrollLock/)

[![NPM version](https://img.shields.io/npm/v/jquery-scroll-lock.svg)](https://www.npmjs.com/package/jquery-scroll-lock/)

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.

> View [demo](http://mohammadyounes.github.io/jquery-scrollLock/#demo)

## Features

* It does not change wheel scrolling speed, user experience will not be affected. 

* You get the same behavior regardless of the OS mouse wheel vertical scrolling speed.

  > On Windows it can be set to one screen or one line up to 100 lines per notch.

* Supports touch screens.

### Install with [NuGet](https://www.nuget.org/packages/jquery-scrollLock/) 

```

Install-Package jquery-scrollLock

```

### Install with Bower

```

bower install jquery-scrollLock

```

### Install with [NPM](https://www.npmjs.com/package/jquery-scroll-lock/) 

```

npm install jquery-scroll-lock --save

```

## Usage

Trigger Scroll Lock via JavaScript: 

```js

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

```

Trigger Scroll Lock via Markup:

```html



     ...



  $('[data-scrollLock]').scrollLock()

```

## Options

|   Options |   Type     | Default    |   Description

|:----------|:----------:|:----------:|:-------------

| animation | `object`   | `false`    | An object defining CSS class(es) to be applied when top or bottom edge is locked. (see [remarks¹](#remarks1))

| keyboard  | `object`   | `false`    | When enabled, keys that causes scrolling will also be locked. (see [remarks²](#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` | [remarks³](#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.

### Remarks¹

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

The `animation` option has two keys:

```js

{

  "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 browser `animationend` event is fired.

### Remarks²

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:

```js

{ "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.

```css

.scrollable{ outline:0; }

```

### Remarks³

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

```javascript

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:

```javascript

$.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.](https://github.com/MohammadYounes/jquery-scrollLock/issues?state=open)

## Commercial License

If you want to use jquery-scrollLock.js to develop commercial sites, themes, projects, and applications, the Commercial license is the appropriate license. With this option, your source code is kept proprietary. Purchase a jquery-scrollLock.js Commercial License at http://www.uplabs.com/posts/scroll-lock-plugin