Auto-scroll modes

The scroll style that fits a follow-along viewer is different from what fits a practice page or a karaoke-style teleprompter. player.scrollMode picks between four strategies for keeping the played bar on screen — continuous flow, only-when-off-screen, smooth glide, or off entirely. Pick a pill in the demo below to see the mode change while the score plays inside a bounded scroll pane.

• Continuous
• OffScreen
• Smooth
• Off

The four modes

ScrollMode values, ordered by how aggressively they scroll:

• Continuous — scroll to the played bar every time the bar changes. The playhead stays anchored, the score flows past. Default.
• OffScreen — scroll only when the played bar leaves the viewport. The score sits still until the reader falls off the page, then jumps to catch up. Good for practice UIs where the reader wants to read ahead.
• Smooth — the viewport glides across each system at the tempo of the music. alphaTab bypasses native smooth scroll and drives the animation itself so the motion matches the beat. Available for both vertical and horizontal layouts.
• Off — no automatic scrolling. Wire your own scroll UI, or let the user pan freely.

The right mode depends on the surface. Continuous suits a follow-along viewer. OffScreen suits practice pages with hand-controlled scrolling. Smooth suits karaoke-style single-line scrolling.

Forcing a scroll manually

api.scrollToCursor() scrolls to the current beat immediately, regardless of the mode — useful for a "back to playhead" button or after the reader manually pans away.

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,
    scrollMode: alphaTab.ScrollMode.OffScreen,
  },
});

document.getElementById('back-to-playhead').addEventListener('click', () => {
  api.scrollToCursor();
});

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

• Scroll target and offsets — choose the element that scrolls and tune the offsets.
• A custom scroll handler — replace the scroll strategy entirely.
• Lazy loading — how off-screen chunks stay out of the DOM until the scroll approaches them.
• scrollMode and scrollToCursor() in the reference, plus the ScrollMode enum.