@svelte-put/lockscroll
Githublocking scroll and hide scrollbar within an HTML element
Compatible with or powered directly bySvelte runes.
Still on Svelte 4? Seethe old docs site here.
Installation
npm install --save-dev @svelte-put/lockscrollpnpm add -D @svelte-put/lockscrollyarn add -D @svelte-put/lockscrollNew to Svelte 5? SeeMigration Guides.
Quick Start
In this minimal example, try clicking on the button below to toggle scroll-lock on<body>.
<script>import {lockscroll }from '@svelte-put/lockscroll';let locked = $state(false);function toggleLockScroll() {locked = !locked;}</script><svelte:body use:lockscroll={locked} /><button class="c-btn mx-auto" onclick={toggleLockScroll}>Toggle lock scroll on body</button>Locking any Scroll Container
InQuick Start,lockscroll is used on the<body>element. In practice, you can placelockscroll on anyscroll container, as shown in the example below.
<script lang="ts">import {lockscroll }from '@svelte-put/lockscroll';let locked = $state(false);</script><button class="c-btn mx-auto" onclick={()=> (locked = !locked)}>Toggle lock scroll for below section</button><section class="bg-bg-soft mt-4 max-h-[400px] overflow-auto rounded px-6" use:lockscroll={locked}>{#each new Array(10) as _}<p>What is Lorem Ipsum? Lorem Ipsum is simply dummy text of the printing and typesettingindustry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, whenan unknown printer took a galley of type and scrambled it to make a type specimen book. It hassurvived not only five centuries, but also the leap into electronic typesetting, remainingessentially unchanged. It was popularised in the 1960s with the release of Letraset sheetscontaining Lorem Ipsum passages, and more recently with desktop publishing software like AldusPageMaker including versions of Lorem Ipsum.</p>{/each}</section>Usage with Svelte Rune
lockscroll can be used with any boolean Svelte rune, nested or not. The following example shows a useful pattern of using a class with rune-based property and a toggle helper. This can, for example, be exported an app-wide singleton and passed around using Svelte context.
<script>import {lockscroll }from '@svelte-put/lockscroll';class ScrollLock {locked = $state(false);toggle(force = !this.locked) {this.locked = force;}}const lock = new ScrollLock();</script><svelte:body use:lockscroll={lock.locked} /><div class="flex justify-center gap-4"><button class="c-btn" onclick={()=> lock.toggle()}>Toggle lock scroll</button><button class="c-btn c-btn--outlined" onclick={()=> lock.toggle(true)}>Force locked</button><button class="c-btn c-btn--outlined" onclick={()=> lock.toggle(false)}>Force unlocked</button></div>lockscroll:toggle CustomEvent
When lock scroll state changes, alockscroll:toggleCustomEvent is fired from the element the action is placed on.
<script lang="ts"> import {lockscroll,type LockScrollDetail }from '@svelte-put/lockscroll'; let locked = false; function toggleLockScroll() { locked = !locked; } function onToggleLockScroll(e: CustomEvent<LockScrollDetail>) { console.log('New scroll lock state:',e.detail.locked); }</script><!-- event should be automatically typed if used in Typescript --><svelte:body use:lockscroll={locked} onlockscrolltoggle={onToggleLockScroll} /><button class="c-btn" onclick={toggleLockScroll}>Toggle lock scroll</button>Migration Guides
From V1 -> V2 (Svelte 5 in Runes mode)
When migrating to v2, you first need to update event attribute syntax to remove colon::
<div use:intersect on:lockscroll:toggle></div><div use:intersect onlockscrolltoggle></div>If you previously used thecreateLockScrollStore helper, that is no longer supported. Instead, extend from the pattern introduced inUsage with Svelte Rune.
<script> import {lockscroll,createLockScrollStore }from '@svelte-put/lockscroll'; import {lockscroll }from '@svelte-put/lockscroll';// can be created in js/ts files or within a Svelte context let lock = createLockScrollStore();class ScrollLock {locked = $state(false);toggle(force = !this.locked) {this.locked = force;}}const lock = new ScrollLock();</script><svelte:body use:lockscroll={lock} /><svelte:body use:lockscroll={lock.locked} /><div class="flex gap-4 justify-center"> <button class="c-btn" on:click={()=> lock.toggle()}>Toggle lock scroll</button> <button class="c-btn c-btn--outlined" on:click={()=> lock.toggle(true)}>Force locked</button> <button class="c-btn c-btn--outlined" on:click={()=> lock.toggle(false)}>Force unlocked</button ></div>Happy locking scroll! 👨💻