scroll-snap

Seamless Scroll Snapping,
Pixel-Perfect Control.

Build engaging web experiences with smooth transitions.
Lightweight. Fast. Flexible.

Lightning Fast

Just 2KB gzipped. Zero dependencies. Built for performance.

Cross Platform

Consistent behavior across all modern browsers.

Full Control

Customize every aspect with a simple yet powerful API.

Installation

npm install scroll-snap

Basic Usage

Here's a simple example of vertical snapping:

import createScrollSnap from 'scroll-snap'

const element = document.getElementById('container')
const { bind, unbind } = createScrollSnap(element, {
  snapDestinationY: '100%'
})
Scroll down ↓
Keep going ↓
Almost there ↓
You made it! 🎉

Horizontal Snapping

Enable horizontal scroll snapping using snapDestinationX:

createScrollSnap(element, {
  snapDestinationX: '100%',
  timeout: 100,
  duration: 300,
})
Scroll right →
Keep going →
You made it! 🎉

Custom Duration

Control the animation speed with custom duration and easing:

createScrollSnap(element, {
  snapDestinationY: '100%',
  duration: 800, // Slower animation
})
Slow scroll ↓
Notice the easing ↓
Smooth! 🎉

Threshold Control

Adjust how far the user needs to scroll before snapping occurs:

createScrollSnap(element, {
  snapDestinationY: '100%',
  threshold: 0.5, // Need to scroll halfway
})
Scroll halfway ↓
Try both directions ↕️
Done! 🎉

Easing Functions

Choose from various easing functions or provide your own:

createScrollSnap(element, {
  snapDestinationY: '100%',
  easing: t => 1 - Math.pow(1 - t, 3), // Cubic
})
Cubic easing ↓
Smooth motion ↓
Perfect! 🎉

Configuration Options

Option Type Default Description
snapDestinationX string | number - Horizontal snap points (e.g., '100%', '500px')
snapDestinationY string | number - Vertical snap points (e.g., '100%', '500px')
timeout number 100 Delay before snapping after scroll ends (ms)
duration number 300 Animation duration (ms)
threshold number 0.2 Scroll distance threshold (0 to 1)
snapStop boolean false Prevents skipping intermediate snap positions when true
showArrows boolean false Shows navigation arrows when hovering the container
enableKeyboard boolean true Enables keyboard arrow keys navigation when focused
easing function linear Animation easing function

Methods

Control scroll snap behavior dynamically after initialization:

Method Description Example
bind() Enables scroll snapping scrollSnap.bind()
unbind() Disables scroll snapping and cleans up listeners scrollSnap.unbind()