Core API

The @jump-section/core package contains the framework-agnostic logic for section tracking and smooth scrolling.

ScrollManager

The main class that orchestrates section detection and scrolling.

Constructor

const manager = new ScrollManager({
  offset: -80,
  behavior: 'smooth',
  hash: false,
  keyboard: false,
  debug: false,
  rootMargin: '-20% 0px -60% 0px',
  focusActiveSection: false,
  stickyElements: [],
  easing: undefined,
});

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | offset | number | 0 | Fixed header offset (px) | | behavior | 'smooth' \| 'auto' \| 'instant' | 'smooth' | Scroll behavior | | hash | boolean | false | Sync URL hash with active section | | keyboard | boolean | false | Alt+Arrow keyboard navigation | | debug | boolean | false | Debug mode | | rootMargin | string | '-20% 0px -60% 0px' | IntersectionObserver rootMargin | | focusActiveSection | boolean | false | Focus section after scroll | | stickyElements | string[] \| HTMLElement[] | [] | Sticky header/footer elements | | easing | (t: number) => number | undefined | Custom easing function |

Methods

  • registerSection(id: string, element: HTMLElement): Register a new section to be tracked. Automatically applies role="region" and aria-labelledby.
  • unregisterSection(id: string): Stop tracking a section.
  • scrollTo(id: string): Programmatically scroll to a registered section.
  • scrollToNext(): Scroll to the next section.
  • scrollToPrev(): Scroll to the previous section.
  • onActiveChange(callback: (id: string | null, meta: { previous: string | null, direction: 'up' | 'down' | null }) => void): Subscribe to active section changes.
  • onProgressChange(sectionId: string, callback: (progress: number) => void): Subscribe to scroll progress (0~1).
  • getSections(): Get registered section IDs.
  • getActiveId(): Get current active section ID.
  • disableSection(id: string): Disable a section from active detection.
  • enableSection(id: string): Re-enable a disabled section.
  • destroy(): Clean up observers and listeners.

Basic Usage

import { ScrollManager } from '@jump-section/core';
 
const manager = new ScrollManager();
 
const el = document.getElementById('my-section');
manager.registerSection('home', el);
 
manager.onActiveChange((id) => {
  console.log('Current active section:', id);
});
 
manager.scrollTo('home');

Advanced Usage

// With sticky header
const manager = new ScrollManager({
  offset: -60,
  stickyElements: ['sticky-header'],
});
 
// Custom easing
const customEasing = (t: number) => t * t * (3 - 2 * t); // smoothstep
const manager = new ScrollManager({
  easing: customEasing,
});
 
// Focus management
const manager = new ScrollManager({
  focusActiveSection: true,
});