Interact

Anything a reader does with the score — following the beat during a lesson, dragging out a phrase to loop it, tapping a note to audition it, snapping the viewport back to the cursor — flows through the APIs in this chapter. Cursors track the current beat, auto-scroll keeps that beat on screen, mouse and touch events fire for every beat and note the user hits, and the bounds lookup returns the same pixel geometry the renderer produced so overlays and hit-tests line up exactly.

Every capability below is available on Web, .NET, and Android unless a card names specific platforms. Follow any card into the reference for the exact signature.

Playback cursor

Cursor and element highlighting

The bar cursor, beat cursor, and beat highlight follow the music together — toggled by two flags and two events.

Customizing cursor colors and animation

Restyle the bar cursor, beat cursor, beat highlight, and selection via CSS classes, and toggle the beat-cursor animation.

A custom cursor handler

Swap in your own ICursorHandler to place and animate the bar and beat cursors with custom logic.

Scroll behavior

Auto-scroll modes

Pick how alphaTab keeps the played bar on screen — Continuous, OffScreen, Smooth, or Off — and force a scroll on demand.

Scroll target and offsets

Pick which element scrolls, add X/Y padding, and choose between native smooth scroll and alphaTab's timed animation.

A custom scroll handler

Assign an IScrollHandler to api.customScrollHandler to control scroll behavior with your own logic.

Lazy loading with IntersectionObserver

Defer DOM insertion of off-screen rendered chunks so large scores load faster and use less memory.

Mouse and touch

Reacting to beat and note clicks

The six sibling events (`beatMouseDown` / `Move` / `Up`, `noteMouseDown` / `Move` / `Up`) with a click-to-seek demo and a per-note click hook demo.

Enabling and disabling interaction

Three toggles — `player.enableSeekToClick`, `player.enablePlaybackRangeSelection`, and `player.resetPlaybackRangeOnClick` — that gate the built-in seek, range-select, and range-reset behavior.

Bounds and hit-testing

Bounds lookup

`api.boundsLookup` maps every rendered beat and note to a screen rectangle so you can hit-test and paint overlays on top of the score.

Beat visibility and note bounds

Use `api.isVisible(beat)` for camera-visible checks and `core.includeNoteBounds` to opt into per-note geometry for precise hit-testing.

Selection

Range selection

Drive the playback-range highlight programmatically with `highlightPlaybackRange`, commit it to a loop with `applyPlaybackRangeFromHighlight`, and reset with `clearPlaybackRangeHighlight`.

Selection change events

Subscribe to `playbackRangeHighlightChanged` to stream selection updates — start beat, end beat, and per-line highlight rectangles — into your own UI.