body-scroll-lock-enhanced

Enhanced version of body-scroll-lock package, main changes:

• fixes body-scroll-lock v4.0.0-beta.0 bug,
• prevents unnecessary scrolling back to section on enableBodyScroll when property scroll-behavior is set to smooth,
• for browsers that support scrollbar-gutter set it instead of padding-right to the body element

---

Why BSL?

Enables body scroll locking (for iOS Mobile and Tablet, Android, desktop Safari/Chrome/Firefox) without breaking scrolling of a target element (e.g. modal/lightbox/flyouts/nav-menus).

Features:

• disables body scroll WITHOUT disabling scroll of a target element
• works on iOS mobile/tablet
• works on Android
• works on Safari desktop
• works on Chrome/Firefox
• works with vanilla JS and frameworks such as React / Vue / Angular
• supports nested target elements (e.g. a modal that appears on top of a flyout)
• can reserve scrollbar width
• -webkit-overflow-scrolling: touch still works

Aren't the alternative approaches sufficient?

• the approach document.body.ontouchmove = (e) => { e.preventDefault(); return false; }; locks the body scroll, but ALSO locks the scroll of a target element (eg. modal).
• the approach overflow: hidden on the body or html elements doesn't work for all browsers
• the position: fixed approach causes the body scroll to reset
• some approaches break inertia/momentum/rubber-band scrolling on iOS

LIGHT Package Size:

Install

pnpm

1pnpm add body-scroll-lock-enhanced

yarn

1yarn add body-scroll-lock-enhanced

npm

1npm install body-scroll-lock-enhanced

Usage examples

JS

1// 1a. Import the functions (for CJS)
2const bodyScrollLock = require('body-scroll-lock-enhanced');
3const disableBodyScroll = bodyScrollLock.disableBodyScroll;
4const enableBodyScroll = bodyScrollLock.enableBodyScroll;
5
6// 1b. Import the functions (for ESM)
7import { disableBodyScroll, enableBodyScroll } from 'body-scroll-lock-enhanced';
8
9// 2. Get a target element that you want to persist scrolling for (such as a modal/lightbox/flyout/nav).
10// Specifically, the target element is the one we would like to allow scroll on (NOT a parent of that element).
11// This is also the element to apply the CSS '-webkit-overflow-scrolling: touch;' if desired.
12const targetElement = document.querySelector('#someElementId');
13
14// 3. ...in some event handler after showing the target element...disable body scroll
15disableBodyScroll(targetElement);
16
17// 4. ...in some event handler after hiding the target element...
18enableBodyScroll(targetElement);

React

1import { useEffect, useRef } from 'react';
2
3// 1. Import the functions
4import { disableBodyScroll, enableBodyScroll, clearAllBodyScrollLocks } from 'body-scroll-lock-enhanced';
5
6const MyComponent = () => {
7  // 2. Get a target element that you want to persist scrolling for (such as a modal/lightbox/flyout/nav).
8  // Specifically, the target element is the one we would like to allow scroll on (NOT a parent of that element).
9  // This is also the element to apply the CSS '-webkit-overflow-scrolling: touch;' if desired.
10  const targetElement = useRef(null);
11
12  const showTargetElement = () => {
13    // ... some logic to show target element
14
15    // 3. Disable body scroll
16    disableBodyScroll(targetElement.current);
17  };
18
19  const hideTargetElement = () => {
20    // ... some logic to hide target element
21
22    // 4. Re-enable body scroll
23    enableBodyScroll(targetElement.current);
24  };
25
26  useEffect(() => {
27    // 5. Useful if we have called disableBodyScroll for multiple target elements,
28    // and we just want a kill-switch to undo all that.
29    // OR useful for if the `hideTargetElement()` function got circumvented eg. visitor
30    // clicks a link which takes him/her to a different page within the app.
31    return () => {
32      clearAllBodyScrollLocks();
33    };
34  }, []);
35
36  return (
37    <div>
38      <div ref={targetElement}>
39        {/* target element content */}
40      </div>
41      <button onClick={showTargetElement}>Show</button>
42      <button onClick={hideTargetElement}>Hide</button>
43    </div>
44  );
45};

Vue

1import { onUnmounted, ref } from 'vue';
2
3// 1. Import the functions
4import { disableBodyScroll, enableBodyScroll, clearAllBodyScrollLocks } from 'body-scroll-lock-enhanced';
5
6// 2. Get a target element that you want to persist scrolling for (such as a modal/lightbox/flyout/nav).
7// Specifically, the target element is the one we would like to allow scroll on (NOT a parent of that element).
8// This is also the element to apply the CSS '-webkit-overflow-scrolling: touch;' if desired.
9const targetElement = ref(null)
10
11const showTargetElement = () => {
12  // ... some logic to show target element
13
14  // 3. Disable body scroll
15  disableBodyScroll(targetElement.value);
16};
17
18const hideTargetElement = () => {
19  // ... some logic to hide target element
20
21  // 4. Re-enable body scroll
22  enableBodyScroll(targetElement.value);
23};
24
25onUnmounted(() => {
26  // 5. Useful if we have called disableBodyScroll for multiple target elements,
27  // and we just want a kill-switch to undo all that.
28  // OR useful for if the `hideTargetElement()` function got circumvented eg. visitor
29  // clicks a link which takes him/her to a different page within the app.
30  clearAllBodyScrollLocks();
31});

Angular

1import { Component, ElementRef, OnDestroy, ViewChild } from '@angular/core';
2
3// 1. Import the functions
4import { disableBodyScroll, enableBodyScroll, clearAllBodyScrollLocks } from 'body-scroll-lock-enhanced';
5
6@Component({
7  selector: 'app-my-component',
8  template: `
9    <div #targetElement>
10      <!-- target element content -->
11    </div>
12    <button (click)="showTargetElement()">Show</button>
13    <button (click)="hideTargetElement()">Hide</button>
14  `,
15})
16export class MyComponent implements OnDestroy {
17  @ViewChild('targetElement', { static: true }) targetElement: ElementRef;
18
19  showTargetElement() {
20    // ... some logic to show target element
21
22    // 3. Disable body scroll
23    disableBodyScroll(this.targetElement.nativeElement);
24  }
25
26  hideTargetElement() {
27    // ... some logic to hide target element
28
29    // 4. Re-enable body scroll
30    enableBodyScroll(this.targetElement.nativeElement);
31  }
32
33  ngOnDestroy() {
34    // 5. Useful if we have called disableBodyScroll for multiple target elements,
35    // and we just want a kill-switch to undo all that.
36    // OR useful for if the `hideTargetElement()` function got circumvented eg. visitor
37    // clicks a link which takes him/her to a different page within the app.
38    clearAllBodyScrollLocks();
39  }
40}

Functions

1disableBodyScroll(targetElement: HTMLElement, options?: BodyScrollOptions): void
2// Disables body scroll for the target element.
3
4enableBodyScroll(targetElement: HTMLElement): void
5// Enables body scroll for the target element.
6
7clearAllBodyScrollLocks(): void
8// Clears all body scroll locks.
9
10toggleBodyScrollLock(targetElement: HTMLElement, options?: BodyScrollOptions & { toggleValue?: boolean }): void
11// Toggles body scroll lock for the target element based on the value parameter in options (value is optional).

Options

reserveScrollBarGap reserveScrollbarGutter

optional, default: false

If the overflow property of the body is set to hidden, the body widens by the width of the scrollbar. This produces an unpleasant flickering effect, especially on websites with centered content. If the reserveScrollbarGutter option is set, this gap is filled by scrollbar-gutter: stable on the html element (or padding-right on the body element, if browser does not support this option). If disableBodyScroll is called for the last target element, or clearAllBodyScrollLocks is called, the scrollbar-gutter (padding-right) is automatically reset to the previous value.

1import { disableBodyScroll } from 'body-scroll-lock-enhanced';
2
3disableBodyScroll(targetElement, { reserveScrollbarGutter: true });

toggleValue

optional (only available in toggleBodyScrollLock), default: undefined

The toggleValue option is a boolean parameter used in the toggleBodyScrollLock function. This parameter determines whether to enable or disable body scroll based on its value.

• If toggleValue is true, the toggleBodyScrollLock function will disable body scroll for the specified target element.
• If toggleValue is false, the toggleBodyScrollLock function will enable body scroll for the specified target element.
• If toggleValue is undefined, the toggleBodyScrollLock function will toggle the current state of body scroll for the specified target element. This means it will disable body scroll if it is currently enabled, and enable body scroll if it is currently disabled.

This option provides a convenient way to manage the body scroll lock state with a single function call.

1import { toggleBodyScrollLock } from 'body-scroll-lock-enhanced';
2
3toggleBodyScrollLock(targetElement, { toggleValue: isTargetElementVisible });

allowTouchMove

optional, default: undefined

To disable scrolling on iOS, disableBodyScroll prevents touchmove events. However, there are cases where you have called disableBodyScroll on an element, but its children still require touchmove events to function.

See below for 2 use cases:

Simple

1disableBodyScroll(container, {
2  allowTouchMove: el => el.tagName === 'TEXTAREA'
3});

More Complex

JavaScript:

1disableBodyScroll(container, {
2  allowTouchMove: (el) => {
3    while (el && el !== document.body) {
4      if (el.getAttribute('body-scroll-lock-ignore') !== null) {
5        return true;
6      }
7
8      el = el.parentElement;
9    }
10  }
11});

HTML:

1<div id="container">
2  <div id="scrolling-map" body-scroll-lock-ignore>
3    ...
4  </div>
5</div>

References

https://medium.com/jsdownunder/locking-body-scroll-for-all-devices-22def9615177 https://stackoverflow.com/questions/41594997/ios-10-safari-prevent-scrolling-behind-a-fixed-overlay-and-maintain-scroll-posi

License

This project is licensed under the MIT License - see the LICENSE file for details.