@svelte-put/lockscroll
GithubCompatible with or powered directly by Svelte runes.
Installation
npm install --save-dev @svelte-put/lockscrollpnpm add -D @svelte-put/lockscrollyarn add -D @svelte-put/lockscrollNew to Svelte 5? See Migration 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
In Quick Start, lockscroll is used on the <body>element. In practice, you can place lockscroll on any scroll 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 typesetting
industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when
an unknown printer took a galley of type and scrambled it to make a type specimen book. It has
survived not only five centuries, but also the leap into electronic typesetting, remaining
essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets
containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus
PageMaker 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, a lockscroll:toggle CustomEvent 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 the createLockScrollStore helper, that is no longer supported. Instead, extend from the pattern introduced in Usage 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! 👨💻