tuax / tua-body-scroll-lock

🔐 Body scroll locking that just works with everything

tua-body-scroll-lock

English | 简体中文

Introduction

tua-body-scroll-lock enables body scroll locking for everything.

• 

• 

• Open in codesandbox
• Open in jsfiddle
• Open in jsbin

Install

Node Package Manager(recommended)

pnpm i tua-body-scroll-lock

CDN

UMD(`tua-bsl.umd.js`)

<!-- unpkg -->
<script src="https://unpkg.com/tua-body-scroll-lock/dist/tua-bsl.umd.js"></script>

<!-- jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/tua-body-scroll-lock/dist/tua-bsl.umd.js"></script>

Minified UMD(`tua-bsl.umd.min.js`)

<!-- unpkg -->
<script src="https://unpkg.com/tua-body-scroll-lock"></script>

<!-- jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/tua-body-scroll-lock"></script>

ESM in browser(`tua-bsl.esm.browser.js`)

<!-- unpkg -->
<script type="module">
  import { lock, unlock } from 'https://unpkg.com/tua-body-scroll-lock/dist/tua-bsl.esm.browser.js'

  lock()
  unlock()
</script>

<!-- jsdelivr -->
<script type="module">
  import { lock, unlock } from 'https://cdn.jsdelivr.net/npm/tua-body-scroll-lock/dist/tua-bsl.esm.browser.js'

  lock()
  unlock()
</script>

Minified ESM in browser(`tua-bsl.esm.browser.min.js`)

<!-- unpkg -->
<script type="module">
  import { lock, unlock } from 'https://unpkg.com/tua-body-scroll-lock/dist/tua-bsl.esm.browser.min.js'

  lock()
  unlock()
</script>

<!-- jsdelivr -->
<script type="module">
  import { lock, unlock } from 'https://cdn.jsdelivr.net/npm/tua-body-scroll-lock/dist/tua-bsl.esm.browser.min.js'

  lock()
  unlock()
</script>

Usage

Normal

import { lock, unlock } from 'tua-body-scroll-lock'

lock()
unlock()

Options

overflowType: 'hidden' | 'clip'

optional, default: 'hidden'

clip is suitable for adapting elements of position: sticky in high-version browsers (Chrome 90 +).

https://caniuse.com/mdn-css_types_overflow_clip

import { lock } from 'tua-body-scroll-lock'

lock(targetElement, { overflowType: 'clip' })

useGlobalLockState: boolean

optional, default: false

Whether to use global lockState for every BSL. It's useful when your page have multiple BSL instances.

TargetElement needs scrolling（iOS only）

In some scenarios, when scrolling is prohibited, some elements still need to scroll, at this point, pass the targetElement.

import { lock, unlock } from 'tua-body-scroll-lock'
const elementOne = document.querySelector('#elementOne')
const elementTwo = document.querySelector('#elementTwo')

// one targetElement
const targetElement = elementOne
// multiple targetElements
const targetElements = [elementOne, elementTwo]

lock(targetElement)
lock(targetElements)
unlock(targetElement)
unlock(targetElements)

The targetElement is not required on the PC and Android.

clearBodyLocks

In the SPA, if you called lock, but forgot to call unlock before jumping to other pages, that is too bad. Because the operation of the page is not restored, such as forbid touchmove, clearBodyLocks is used to clear all side effects. Sure, you can also call unlock, but if you have called lock multiple times, you must call unlock multiple times, which is very unfriendly.

Examples

Please see these examples:

• vue
• react
• vanilla

Contributors

Thanks goes to these wonderful people (emoji key):

evinma 💻 📖 🚇 🌍

StEve Young 💻 📖 🚇 🌍

li2go 💻 🐛

songyan,Wang 💻 🐛

Даниил Пронин 🐛

阿卡琳 🐛

falstack 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

inspired by body-scroll-lock

tua-body-scroll-lock's Issues

bug: 代码没过 babel 编译

版本
Version 0.3.0

描述一下 bug
简洁清晰地描述一下 bug。如果方便的话，添加一些截图描述你的问题。

https://unpkg.com/[email protected]/dist/tua-bsl.umd.js

可以看到 const、箭头函数...

预期行为
简洁清晰地描述一下预期行为。

代码编译到 es5

附加上下文
添加一些问题的相关上下文。

0.2.2 版本是编译了的...

https://unpkg.com/[email protected]/dist/tua-bsl.umd.js

bug: lock fails with native dialog modal

Version
1.2.1

Describe the bug
When attempting to lock scroll on showing a native dialog modal, it is still possible to scroll the content behind the modal.

To Reproduce

1. Create an HTML dialog element
2. Call dialog.showModal()
3. Call lock(dialogRef)
4. Attempt to scroll

Expected behavior
The content should not scroll behind the modal after lock is called.

Additional context
Replacing $body from document.body with document.documentElement fixes the issue in setOverflowHiddenPc.

bug: Cannot read property 'clientY' of undefined

Version 1.0.0

ios 11

error: Cannot read property 'clientY' of undefined

HTMLDivElement.i.ios.f.indexOf.e.ontouchstart()

The `body-scroll-lock` demo calls the wrong methods

btn.onclick = function() {
  modalOne.style.display = 'block'
  bodyScrollLock.enableBodyScroll(targetOne)
}
modalBtn.onclick = function() {
  modalTwo.style.display = 'block'
  bodyScrollLock.enableBodyScroll(targetTwo)
}

If you call disableBodyScroll instead of enableBodyScroll, you'll find that the body-scroll-lock demo works just fine with the original package.

Incompatible with position:sticky on Android

Version
Version 1.4.0

Describe the bug
There's some UA sniffing code in the library which targets Android and sets the body element to be position: fixed with a top offset to fake a scroll to the current scroll position. Unfortunately this makes any headers that use position:sticky stop being sticky.

To Reproduce
Steps to reproduce the behavior:

1. Have a site with a sticky header and a mobile navigation that triggers the body scroll lock
2. The mobile nav should have a top offset so that the sticky header is still visible when it's on
3. Switch on the mobile nav
4. See that the sticky header has disappeared offscreen.

If you don't have an Android device you can see this problem easily using the device emulator tools in Chrome and Firefox's inspectors which pass through the appropriate UA string.

安卓5版本unlock()后点击输入框页面会白屏

版本
Version [e.g. 0.1.0]

描述一下 bug
简洁清晰地描述一下 bug。如果方便的话，添加一些截图描述你的问题。

复现 bug
复现的步骤：

1. 首先 '...'
2. 点击了 '...'
3. 滚动到了 '...'
4. 看到了错误

建议 fork 以下某个平台的 demo 复现一下：

• jsbin: https://jsbin.com/cafiful/edit?output
• codepen: https://codepen.io/buptsteve/pen/PvNQjP
• jsfiddle: https://jsfiddle.net/buptsteve/6u8g3Lf5/
• codesandbox: https://codesandbox.io/s/o73z4jy5q9

预期行为
简洁清晰地描述一下预期行为。

附加上下文
添加一些问题的相关上下文。

bug: Demo link is old, broken on Android

Need to clean up the demo links....

On the Github page (https://github.com/tuateam/tua-body-scroll-lock), there's a link "Can't believe it? Please try this demo with BSL yourself." and itdoesn't seem to work (Chrome 86 on Android, Firefox 81.0.2 on MacOS).

Meanwhile, another demo link further down the page, demo.vue, does work across the above stated browsers.

How to use React refs instead of queryselectors?

Any advice would be greatly appreciated.

feat: Better documentation

Is your feature request related to a problem? Please describe.
It can be difficult for less experienced developers to know how to use this package.

Describe the solution you'd like
A clearer explanation of how to use the lock and unlock functions. The current usage explanation is just:
import { lock, unlock } from 'tua-body-scroll-lock'
lock()
unlock()
The import line is clear enough. But how do you use lock() and unlock()? Where do you put them? Do these functions take parameters? An example on CodePen or similar would be great.

Describe alternatives you've considered
I'm going to try the useLockBodyScroll package instead. At least I can find an example of how to use it.

Additional context
Thanks everyone on this team for your great work!

safari浏览器 当工具栏收起时 滑动手机下方 依然有滑动穿透

版本
Version [v1.1.0]

描述一下 bug
safari浏览器 当工具栏收起时 滑动手机下方 依然有滑动穿透

7f1010ae22c44210f89b17048842da4e.mp4

视频中最后滑动的位置为手机的下方

feat(docs): add english readme

feat: Inhibit body content shift when toggling scroll lock

Is your feature request related to a problem? Please describe.
When enabling scroll lock, the body's scroll bar disappears, resulting in a horizontal shift of the body content (around 15-17px depending on the browser).

Describe the solution you'd like
For scrolling to be disabled and the body content to NOT shift.
Potential options:
A - Maintain a scroll bar even with scrolling disabled
--- or ---
B - Add padding to the body content, that matches the width of the scroll bar

Describe alternatives you've considered
Looked at other plugins and manual solutions online.

feat: pretty demo

你的功能请求是否与某些问题相关？请描述

1. 目前的 demo 还削微有些简陋，需要美化一下。
2. 大家在反馈 bug 或者提 pr 的时候一般都需要带上 demo，目前还不是很方便。

描述您想要的解决方案

1. 美化 demo 方面

• 将 README.md 转换成 html 嵌入
• 引用一些 css 库进一步美化

2. 复现模板

• 各个平台都放一个，方便大家 fork
• 各个平台的 demo 代码和项目本身的 demo 代码保持同步
  • codesandbox: https://github.com/BuptStEve/tua-bsl-demo

描述你考虑过的备选方案

• 使用 vuepress？
• 使用这个插件？ https://github.com/BuptStEve/vuepress-plugin-demo-code

附加上下文

• bsl demo: https://codepen.io/buptsteve/pen/EJoKQK
• tua-bsl demo: https://tuateam.github.io/tua-body-scroll-lock/
• #14 : https://codesandbox.io/s/mor5o68jp?fontsize=14
• tua-bsl v0.2.0-0 demo: https://codepen.io/buptsteve/pen/joqGPV

bug: link on npm leads to 404

The links on NPM leads to a 404.
Seems like the project was moved from tuateam to tuax after the latest 1.4.0 release.
It's fixed in package.json, but there has been no release since.
Would it be possible to create a new npm release, this would fixed the issue by updating the data on npm.

feat: hope can fit ios 11

i founded it cannot fit ios 11.2 on the iPhone 7 Plus.
actually in current market many people still use the ios 11 ,
hope this best repositories can fit this system.

feat: add clearBodyLocks api

In the SPA, if you called lock, but forgot to call unlock before jumping to other pages, that is too bad. Because the operation of the page is not restored, such as forbid touchmove，clearBodyLocks is used to clear all side effects. Sure, you can also call unlock, but if you have called lock multiple times, you must call unlock multiple times, which is very unfriendly.

feat: support scrolling in nested elements

The library currently allows only one target element to be scrollable. I have the use case where a modal contains multiple elements (sliders) that also need to be scrollable.

The body-scroll-lock library allows for this to happen through a allowTouchMove function that the user of the lib can supply to validate if the element is scrollable.

Would this be something you consider to implement?

可以支持一下uni-app吗

既然pc、移动端和客户端都支持了，那么请大神也支持一下小程序（微信，支付宝）这些吧，感激不尽

bug: demo not working properly on iOS chrome browser

Version
latest

Describe the bug
open demo from chrome browser and try to scroll tua example with modal open, body would be scrollable too

Expected behavior
no scroll on body and scroll on target 1 and 2

bug: Broken reversed scrollbar on desktop

Version
Version 1.3.0

Describe the bug
After updating to 1.3.0 padding-right on html gets set to 0 on desktop.

Providing a reproduction demo will be better (you can pick a platform below and fork the demo):

• codepen: https://codepen.io/kyrylo-soulandwolf/pen/MWzQYwK

Expected behaviour
Padding is to be set on html to reverse the width of the scroll bar.

feat: options for overflow

Tua-body-scroll-lock works great and thank you for a nice package!

But I have some trouble using this package together with elements that uses position: sticky (For example headers, top menus etc.)

In some cases overflow: hidden is exactly what I want, but in other cases this doesn't simply work because I use elements that has position: sticky.

It would be great if I could pass some type of options object where I can choose (maybe among other things) what type of overflow value I want.

Br,
Adam

Demo broken on Safari

Describe the bug
Scrolling doesn’t work on the CodePen demo: https://codepen.io/buptsteve/full/EJoKQK

To Reproduce

1. Go to https://codepen.io/buptsteve/full/EJoKQK
2. Click the 'click me to show the dialog' button
3. Click outside the dialog to close the dialog
4. Page no longer is scrollable

feat: setOverflowHiddenPc make optional

Is your feature request related to a problem? Please describe.
Some moments, I don't need to use setOverflowHiddenPc. Because it handles another function sometimes

Describe the solution you'd like
The ability to pass an argument to it as an option, like
lock(el, { reserveScrollBarGap: true })

Describe alternatives you've considered
You can do like a body-lock

Thanks in advance

Use one state for multiple instances

Is your feature request related to a problem? Please describe.
I wrote a plugin (needed at work) that I embed on websites. This plugin uses BSL. And the sites that use this plugin also use BSL. The problem is that inside the plugin, the lock/unlock functions use their lockedElements, lockedNum and the same on the site. That is, if you close all the windows in the plugin, but there are open ones on the site, the plugin will execute unLockCallback() because it does not know that there are open popups on the site.

Describe the solution you'd like
Use window.bsl object for statement. In this case all instances BSL will has access to lockedElements and lockedNum.

Describe alternatives you've considered
// empty

Additional context
// empty