Quick Start

Creating a drag-to-scroll interface requires a specific relationship between your HTML structure, your CSS constraints, and the ScrollBooster JavaScript initialization.

This guide will walk you through a minimal "Hello World" implementation and explain why each piece is necessary.

1. The HTML Structure

ScrollBooster relies on a parent-child relationship in the DOM.

  1. The Viewport: The outer container. It acts as a static "window" or "mask" through which the user looks.
  2. The Content: The inner element. It contains the actual data (images, cards, maps) and is physically larger than the viewport.
<!-- The fixed-size Viewport -->
<div class="viewport">
    <!-- The oversized Content -->
    <div class="content">
        <h2>Drag anywhere to explore</h2>
        <img src="massive-map.jpg" alt="Map" />
    </div>
</div>

Note: If you do not explicitly pass a content element to ScrollBooster, it will automatically assume the first child of the viewport is the content.

2. Essential CSS Constraints

The layout will fail if CSS does not properly constrain the viewport and expand the content. 

.viewport {
    /* 1. Restrict the viewport size */
    width: 500px;
    height: 400px;

    /* 2. Hide the spilling content. 
          If using scrollMode: 'native', change this to 'scroll' or 'auto' */
    overflow: hidden; 

    /* 3. Provide visual cues for interactivity */
    cursor: grab;
    border: 2px solid #ccc;
}

.viewport:active {
    /* Update cursor during the drag action */
    cursor: grabbing;
}

.content {
    /* 4. Ensure the content is physically larger than the viewport */
    width: 1500px;
    height: 1500px;

    /* 5. Optional but recommended: Prevent text highlighting during drag */
    user-select: none;
    background: repeating-linear-gradient(45deg, #f0f0f0, #f0f0f0 20px, #e0e0e0 20px, #e0e0e0 40px);
}

Why user-select: none?

When users click and drag wildly across the screen, browsers natively attempt to highlight text. This causes UX friction. While ScrollBooster has built-in logic to handle text nodes via the textSelection option, applying user-select: none via CSS is the most performant way to prevent accidental highlighting globally in your draggable area.

3. Initializing ScrollBooster

With the DOM and CSS prepared, we can attach ScrollBooster. In this example, we will utilize the library's built-in scrollMode: 'transform', which automatically translates the physics calculations into CSS transform: translate(x, y) strings on the .content node.

import ScrollBooster from 'scrollbooster';

// 1. Select the viewport DOM element
const viewport = document.querySelector('.viewport');
const content = document.querySelector('.content');

// 2. Instantiate the physics engine and event listeners
const sb = new ScrollBooster({
    viewport: viewport,   // Required
    content: content,     // Optional: defaults to viewport.children[0]

    // Tell ScrollBooster to handle the DOM updates automatically using CSS transforms
    scrollMode: 'transform',

    // Physics configurations
    bounce: true,         // Rubber-band effect at edges
    friction: 0.05,       // How fast the gliding stops
});

Congratulations! You now have a fully functional, kinetic drag-to-scroll container.

Next Steps

While scrollMode: 'transform' is great for quick setups, you might need to handle native scrolling, prevent clicks on internal buttons, or support mouse wheels. Dive into the Usage Guide & Core Concepts to explore advanced implementations.