scroll-snap

scroll-snap

Overview

scroll-snap is a powerful yet lightweight TypeScript library that provides smooth and customizable page snapping functionality. Built as a modern implementation of CSS Scroll Snap.

Features

• 🪶 Lightweight (~2KB gzipped)
• 🌐 Cross-browser support
• 💪 Zero dependencies
• 🎯 TypeScript ready
• ⚡ Smooth animations
• 🎨 Customizable settings
• ⌨️ Keyboard navigation support
• 🖱️ Optional navigation arrows

Installation

yarn add scroll-snap

Basic Usage

import createScrollSnap from 'scroll-snap'

const element = document.getElementById('container')
const { bind, unbind } = createScrollSnap(element, {
  snapDestinationY: '100%',
})

React Usage

Check out the React Hooks demo to see how to integrate scroll-snap in a React application.

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
showArrows	boolean	false	Shows navigation arrows when hovering
enableKeyboard	boolean	true	Enables keyboard arrow keys navigation
easing	(t: number) => number	linear	Animation easing function

Examples

Vertical Snapping

const scrollSnap = createScrollSnap(element, {
  snapDestinationY: '100vh',
  duration: 300,
  easing: t => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
})

Horizontal Scrolling Gallery

const scrollSnap = createScrollSnap(element, {
  snapDestinationX: '100%',
  showArrows: true,
  enableKeyboard: true
})

Custom Threshold

const scrollSnap = createScrollSnap(element, {
  snapDestinationY: '50vh',
  threshold: 0.4, // Requires more scroll distance to trigger snap
})

API Reference

Methods

bind()

Enables scroll snapping and attaches event listeners.

unbind()

Disables scroll snapping and removes event listeners.

Development

# Clone the repository
git clone https://github.com/lucafalasco/scroll-snap.git
cd scroll-snap

# Install dependencies
yarn

# Start development server with examples
yarn dev

# Run unit tests
yarn test

# Run integration tests
yarn test:e2e

# Build for production
yarn build

The dev server will start at http://localhost:8080 with hot reloading enabled and a playground environment for testing.

Contributing

• Fork the repository
• Create your feature branch: git checkout -b feature/my-feature
• Commit your changes: git commit -am 'Add my feature'
• Push to the branch: git push origin feature/my-feature
• Submit a pull request

Browser Support

• Chrome 61+
• Firefox 63+
• Safari 11+
• Edge 79+

License

MIT © Luca Falasco