npm install @furman1331/page-scroller

Full-page scrolling made simple

A lightweight TypeScript library for smooth full-page scrolling with sections, horizontal slides, keyboard & touch navigation, and programmatic control.

Get Started View on GitHub

bash

npm install @furman1331/page-scroller

Everything you need

A complete toolkit for full-page scrolling experiences.

⬛

Full-page sections

Each section takes up the full viewport. Scroll snaps smoothly between them.

➡️

Horizontal slides

Nest horizontal slides inside any section for multi-step content.

🔷

TypeScript-first

Fully typed API. Autocomplete and compile-time safety out of the box.

⌨️

Keyboard & touch

Works with arrow keys, mouse wheel, swipe gestures, and touch events.

🔄

Auto & manual modes

Automatic full-page scroll or manual mode for mobile and custom layouts.

🎯

Programmatic navigation

Jump to any section or slide with a single function call.

Quick Start

Up and running in under a minute.

Install

Add the package to your project.

Wrap your sections

Add the required HTML structure with id and class names.

Initialize

Call initPageScroller in a useEffect with the wrapper selector.

Done

Scroll through your sections smoothly.

bash

npm install @furman1331/page-scroller
# or
bun add @furman1331/page-scroller

Usage Example

A complete React component setup.

tsx

"use client"

import { usePageScroller, onDestroy } from "@furman1331/page-scroller"
import { useEffect } from "react"

export function App() {
  const { initPageScroller } = usePageScroller({
    onSectionChange: ({ afterIndex }) =>
      console.log("Section:", afterIndex),
  })

  useEffect(() => {
    initPageScroller("#page-scroller")
    return () => onDestroy()
  }, [])

  return (
    <div id="page-scroller">
      <div className="page-scroller__section">
        <h1>Section 1</h1>
      </div>
      <div className="page-scroller__section">
        <h1>Section 2</h1>
      </div>
    </div>
  )
}

Slide 1 — Sections

Each full-page section snaps into view as you scroll. No CSS tricks needed.

1 / 3

Slide 2 — Horizontal Slides

Inside any section, add horizontal slides for multi-step walkthroughs.

2 / 3

Slide 3 — Programmatic Control

Jump to any section or slide via the API. Pair with your own navigation UI.

3 / 3

Horizontal Slides

Add the page-scroller-slide="true" attribute to child elements inside a section to enable horizontal slides.

HTML

html

<div id="page-scroller">
  <div class="page-scroller__section">
    <!-- Section WITHOUT slides -->
    <h1>Section 1</h1>
  </div>

  <div class="page-scroller__section">
    <!-- Section WITH horizontal slides -->
    <div page-scroller-slide="true">
      <h2>Slide A</h2>
    </div>
    <div page-scroller-slide="true">
      <h2>Slide B</h2>
    </div>
    <div page-scroller-slide="true">
      <h2>Slide C</h2>
    </div>
  </div>
</div>

React / TSX

tsx

export function MySection() {
  return (
    <div className="page-scroller__section">
      {[1, 2, 3].map((n) => (
        <div key={n} {...{ "page-scroller-slide": "true" }}>
          <h2>Slide {n}</h2>
        </div>
      ))}
    </div>
  )
}

Tip: Sections without slide children behave as full-page vertical sections. Sections with one or more slide children switch to horizontal scroll automatically.

API Reference

All methods from usePageScroller(options?) and standalone imports.

initPageScroller(selector)→ void

Initialize on the given CSS selector

changeSectionBySpecificIndex(index)→ void

Navigate to section by zero-based index

changeSectionByDirection(direction)→ void

"up" | "down"

Method	Returns	Description
`initPageScroller(selector)`	void	Initialize on the given CSS selector
`changeSectionBySpecificIndex(index)`	void	Navigate to section by zero-based index
`changeSectionByDirection(direction)`	void	"up" \| "down"

Programmatic Navigation

Jump to any section directly using changeSectionBySpecificIndex(index). Try the buttons below.

tsx

import { changeSectionBySpecificIndex } from "@furman1331/page-scroller"

// Jump to section by index (0-based)
changeSectionBySpecificIndex(0) // Hero
changeSectionBySpecificIndex(5) // API Reference

Mobile & Manual Mode

Switch between automatic full-page scrolling and manual mode — where the user scrolls normally. Useful for mobile layouts.

Current mode:⚡ Automatic

tsx

import { changeScrollingMode } from "@furman1331/page-scroller"

// Switch to manual (default for mobile)
changeScrollingMode("manual")

// Switch back to automatic
changeScrollingMode("automatic")

// Responsive initialization
useEffect(() => {
  initPageScroller("#page-scroller")
  if (window.innerWidth < 768) {
    changeScrollingMode("manual")
  }
}, [])