Native Scrolling Example

While CSS transforms are the most performant way to move a canvas, there are many scenarios where you want to maintain Standard Browser Scrollbars.

If you are building a Kanban board (like Trello), a horizontal product gallery, or an application where users might want to click and drag the native scrollbar thumb, you should use native scrolling.

How it Works

Instead of applying CSS transform, ScrollBooster calculates the drag physics and sets the .scrollTop and .scrollLeft DOM properties of the viewport directly.

Because of this, ScrollBooster can stay perfectly in sync. If the user grabs the native scrollbar, the browser fires a scroll event, ScrollBooster intercepts it, and updates its internal position.x and position.y math to match.

The Code

Notice that .viewport uses overflow: scroll (or auto) instead of overflow: hidden.

<style>
    .viewport {
        width: 400px;
        height: 400px;
        border: 5px solid #000;
        /* CRITICAL: Allow native scrollbars to exist */
        overflow: auto; 
        cursor: grab;
    }

    .viewport:active {
        cursor: grabbing;
    }

    .content {
        width: 1000px;
        height: 1000px;
        background: lightblue;
    }
</style>

<div class="viewport">
    <div class="content">
        <h1>Native Drag Scroll</h1>
        <p>Notice the native scrollbars on the right and bottom.</p>
    </div>
</div>

<script type="module">
    import ScrollBooster from 'scrollbooster';

    const viewport = document.querySelector('.viewport');

    new ScrollBooster({
        viewport: viewport,

        // Setting scrollMode to 'native' automates updating viewport.scrollTop & scrollLeft.
        // It eliminates the need to write an onUpdate() callback.
        scrollMode: 'native',

        // Allow trackpad swipes to fuel the physics engine
        emulateScroll: true 
    });
</script>

Trade-offs of Native Scrolling

Pros:

• Accessibility: Screen readers and keyboard navigation (tabbing through elements) will natively scroll the container without you having to write custom math to keep the ScrollBooster state in sync.
• User Familiarity: Users recognize native scrollbars and know they can click and drag them for fast navigation.

Cons:

• Performance: Updating scrollTop and scrollLeft forces the browser to trigger a layout reflow. On massive, complex DOM trees, this can result in dropped frames compared to hardware-accelerated CSS transforms.
• Bouncing Limitations: Native scroll bouncing (rubber-banding) on iOS/Mac often conflicts with ScrollBooster's javascript physics bounce. It's often best to set bounce: false in ScrollBooster when using native mode to prevent chaotic stuttering at the edges.