Scroll target and offsets

A sticky toolbar above the score, a chord chart docked to the top, a lyrics rail on the side — every one of these shifts where the played bar should land inside the viewport. Four PlayerSettings fields cover it: which element scrolls, how much padding to leave around the target bar, and whether the browser or alphaTab drives the animation. Slide the offsets in the demo below to move the played bar's landing spot inside the bounded scroll pane.

• Continuous
• OffScreen
• Smooth
• Off

scrollOffsetX0scrollOffsetY-40

• Native smooth
• alphaTab timed

Which element scrolls

player.scrollElement names the element alphaTab scrolls. Two forms:

• A CSS selector string — resolved once, at API construction time. Default is html,body so the browser window scrolls.
• An HTMLElement — the direct reference. Use this when the container sits inside a scrollable panel: pass the panel, not the container.

Point it at whichever ancestor actually has overflow: auto. Point it at the wrong element and the score stays put.

Offsets

player.scrollOffsetX and player.scrollOffsetY add padding between the played bar and the edge of the scroll container. Positive values push the bar away from the top-left corner. Use them to leave room for a sticky toolbar, a chord chart, or a lyrics rail.

Native vs custom smoothing

player.nativeBrowserSmoothScroll defaults to true. alphaTab hands the scroll to the browser's built-in smooth-scroll implementation. It respects the reader's prefers-reduced-motion and integrates with browser gestures.

Set it to false and alphaTab animates the scroll itself over player.scrollSpeed milliseconds (default 300). The custom animation is what scrollSpeed controls — with native smoothing on, the browser picks the duration and scrollSpeed has no effect.

Show it in code

import * as alphaTab from '@coderline/alphatab';

const container = getAlphaTabContainer();
const api = new alphaTab.AlphaTabApi(container, {
  core: { file: '/scores/song.gp' },
  player: {
    playerMode: alphaTab.PlayerMode.EnabledAutomatic,
    scrollElement: document.getElementById('score-scroll-pane'),
    scrollOffsetY: -80,
    nativeBrowserSmoothScroll: false,
    scrollSpeed: 500,
  },
});

getAlphaTabContainer() is a placeholder for the platform-specific step of obtaining the render target. Every other line runs unchanged on all three runtimes.

Where to look next

• Auto-scroll modes — pick when the scroll fires.
• A custom scroll handler — replace the scroll strategy.
• scrollElement, scrollOffsetX, scrollOffsetY, scrollSpeed, nativeBrowserSmoothScroll in the reference.