Cursor covered by iPhone Dynamic Island - Tested on PWA on iPhone 16 Pro Max

[AvaTheArchitect]

The issue seems to be that AlphaTab and the current default system, when in Horizontal Mode on an iPhone and in this case it's an iPhone 16 Pro Max, the cursor moves behind the dynamic island each time. As we know our current AlphaTab set up does not have an ability to make the default cursor "static" or "fixed" so that only the Canvas would move continuously underneath. As I understand it we would need to create a custom cursor and deactivate the AlphaTab Cursor.

In the meantime, here is what we have tried or are trying and not sure if this will make any difference:

If changing the offset percentage from 15% to 25% had no visible effect, it is likely because AlphaTab does not have a single scrollOffset property. Using an undefined property like scrollOffset causes AlphaTab to fall back to its default behavior, which is to place the cursor at the very edge of the viewport.

To clear the Dynamic Island on an [iPhone 16 Pro Max], you must use the specific scrollOffsetX and scrollOffsetY properties.

Correcting the Configuration
Replace the generic scrollOffset with the explicit X and Y properties:
javascript
// ✅ Correct Properties for V97+

api.settings.player.scrollOffsetX = container.clientWidth * 0.25; // Horizontal offset
api.settings.player.scrollOffsetY = 0; // Vertical offset

// ✅ Required for the offset to take effect
api.settings.player.scrollMode = 1; // Must be ScrollMode.Continuous (1)
api.settings.player.scrollElement = container;

// Apply changes
api.updateSettings();
api.render();
Use code with caution.

History of attempts to fix this, we started at .15 and then tried adjusting to .25 and does not appear to look any different. Conclusions:

Why 25% Didn't Work Previously
Property Name: Claude likely used scrollOffset, which does not exist in the AlphaTab API. The engine simply ignored it.

Scroll Mode: If scrollMode is set to OffScreen (2), AlphaTab ignores your offsets until the cursor actually leaves the screen. Using Continuous (1) ensures the offset is active at all times.
Viewport Scaling: On high-density displays like the iPhone 16 Pro Max, the scrollElement must be explicitly set to your container (not html or body) to ensure the offset is calculated against the correct pixel grid.
Adjusting for the Dynamic Island
The Dynamic Island on the iPhone 16 Pro Max in landscape typically occupies about 50-60 pixels of safe area from the left edge.
15% Offset: ~140px (Safely clears the island).
25% Offset: ~233px (Centers the cursor more toward the middle-left).
If you apply scrollOffsetX (not scrollOffset) and still see no change, check your browser console for any errors related to api.updateSettings(). You may need to trigger a re-render using api.render() for the new scrolling boundaries to be calculated.
Safari Browser console shows no errors, it appears the previous fix is being ignored.

[Danielku15]

Can you try to rephrase more precisely what is the current and your expected behavior? I think I don't understand your problem. If the device has additional "overlays" or "cut-outs" its something you have to handle in our app to place alphaTab accordingly. The screenshot doesn't show me anything regarding this iPhone dynamic islands.

The scroll offset is accounted during scrolling to leave the configured space left or on top. If there is an "overlay" or invisible section over the browser window, there is nothing alphaTab can do. In such a case you should scale down the viewport in that case so that the right edge of the scroll element is on the left edge of any overlay.

You can change from "body" scrolling to a custom scrollable (overflow: auto) element: https://alphatab.net/docs/reference/settings/player/scrollelement

[AvaTheArchitect]

https://drive.google.com/file/d/1VIWRZTtL2O4jtGN7-Kns4Mq4lrE2exM5/view?usp=drivesdk https://youtube.com/shorts/9JDgG0daPec?si=OLchUGALmfoSF_Ii My apologies, the previous image I attached was showing the issue. This is a better illustration. For everyone that currently uses AlphaTab on Mobile App or Mobile devices in this case iPhone. By default the way that AlphaTab is set up … the cursor is hiding behind that black box that is always at the top of the screen or in this case the left edge in the horizontal view. The Cursor should either by fixed by default of AlphaTab at .30 or whatever it would need to be so it stays away from that black box or Dynamic Island as they call it on the iPhones. I am going to check again the article docs you shared and see if that changes anything, but so far it seems that this may be a bug or something that cannot be resolved without using a custom set up. The auto-scroll right now moves one measure at a time (as we know) instead of a steady continuous scroll.

…

On Thu, Dec 18, 2025 at 6:02 AM Daniel Kuschny ***@***.***> wrote: Can you try to rephrase more precisely what is the current and your expected behavior? I think I don't understand your problem. If the device has additional "overlays" or "cut-outs" its something you have to handle in our app to place alphaTab accordingly. The screenshot doesn't show me anything regarding this iPhone dynamic islands. The scroll offset is accounted during scrolling to leave the configured space left or on top. If there is an "overlay" or invisible section over the browser window, there is nothing alphaTab can do. In such a case you should scale down the viewport in that case so that the right edge of the scroll element is on the left edge of any overlay. You can change from "body" scrolling to a custom scrollable (overflow: auto) element: https://alphatab.net/docs/reference/settings/player/scrollelement — Reply to this email directly, view it on GitHub <#2440 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQF5GAEATJBYHWWA4O34CKXXDAVCNFSM6AAAAACPMXHGM2VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKMRYHE4DKNQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[AvaTheArchitect]

Please check the videos and let me know your thoughts for a future development for a fixed cursor and continuous auto-scroll Songsterr like. Meanwhile, with all your suggestions and multiple testings... we did get the cursor out from the Dynamic Island.... it's still not ideal yet but much closer until a custom or fixed cursor set up can be done. I just wanted to share what we did for this as well as a Canvas Render issue in which the orientation changes were causing the staff to be at the top of the screen or the single row unified staff to not change back to multiple rows during the rotations. This was our best solution: Summary: AlphaTabRenderer Mobile Landscape & Orientation Fixes Session Date: December 18th, 2025 Final Version: V97.26 ------------------------------ Problem 1: Cursor Disappearing Behind Dynamic Island (iPhone 16 Pro Max) *Symptom:* In landscape mode, the cursor would start in the correct position but reset behind the Dynamic Island each time auto-scroll moved to a new measure. *Root Cause:* - Used non-existent scrollOffset property (AlphaTab silently ignored it) - Fixed pixel values don't adapt to different screen sizes *Solution:* javascript // ✅ CORRECT: Use scrollOffsetX and scrollOffsetY (NOT scrollOffset!)(api.settings.player as any).scrollOffsetX = container.clientWidth * 0.45;(api.settings.player as any).scrollOffsetY = 0; // ✅ REQUIRED: Must be Continuous mode for offsets to work api.settings.player.scrollMode = alphaTab.ScrollMode.Continuous; // ✅ REQUIRED: Explicit scroll element api.settings.player.scrollElement = container; // ✅ SMOOTH SCROLLING: Disable native browser scroll for steady movement(api.settings.player as any).nativeBrowserSmoothScroll = false;(api.settings.player as any).scrollSpeed = 200; *Key Settings Table:* Property Value Purpose scrollOffsetX container.clientWidth * 0.45 45% offset (~1 inch from edge like Songsterr) scrollOffsetY 0 No vertical offset in landscape nativeBrowserSmoothScroll false Enables AlphaTab's steady animation engine scrollSpeed 200 Smooth animation (lower = faster) scrollMode Continuous (1) Required for offsets to work scrollElement container Explicit container reference ------------------------------ Problem 2: Track Name Partially Hidden by Dynamic Island *Symptom:* Track name label next to staff was slightly covered by Dynamic Island. *Solution:* Add CSS safe-area padding to the container: javascript style={{ paddingLeft: 'env(safe-area-inset-left, 0px)', paddingRight: 'env(safe-area-inset-right, 0px)',}} This shifts the entire AlphaTab viewport away from the notch/island automatically based on device. ------------------------------ Problem 3: Layout Not Switching Properly on Orientation Change *Symptom:* Rotating between portrait and landscape would sometimes leave the layout in the wrong mode (single row instead of multi-row, or vice versa). Staff would appear at wrong position (top instead of bottom in landscape). *Root Cause:* - Timing issues with browser rotation animation - Scroll positions not being reset - Single render not sufficient to recalculate layout *Solution - Aggressive Re-render Sequence:* javascript // 1. Reset ALL scroll positions BEFORE changing layoutconst resetScrollPositions = () => { container.scrollTop = 0; container.scrollLeft = 0; scrollContainerRef?.current?.scrollTop = 0; scrollContainerRef?.current?.scrollLeft = 0; document.documentElement.scrollTop = 0; document.documentElement.scrollLeft = 0; document.body.scrollTop = 0; document.body.scrollLeft = 0;}; // 2. Multi-step re-render sequenceawait api.updateSettings();resetScrollPositions();window.dispatchEvent(new Event('resize'));await delay(100); api.render(); // First renderawait delay(200);resetScrollPositions();window.dispatchEvent(new Event('resize'));await delay(100); api.render(); // Second render (ensures layout correct)await delay(150);resetScrollPositions(); // Final scroll resetwindow.dispatchEvent(new Event('resize')); *Additional Fixes:* - *Debounce (400ms):* Allows iOS rotation animation to complete - *Concurrent processing prevention:* Skip if already processing - *Triple event listeners:* matchMedia, resize, AND orientationchange for iOS - *Orientation tracking:* Skip if orientation hasn't actually changed

…

------------------------------ Key Learnings from AlphaTab Devs 1. *scrollOffset does NOT exist* - must use scrollOffsetX and scrollOffsetY 2. *nativeBrowserSmoothScroll = false* enables AlphaTab's custom animation engine (stops jumpy scrolling) 3. *scrollMode must be Continuous (1)* for scroll offsets to work - OffScreen (2) ignores offsets until cursor hits edge 4. *scrollElement must be explicit* - don't rely on default html, body which causes issues on iOS PWAs 5. *CSS env(safe-area-inset-*) is the "professional fix"* for Dynamic Island/notch issues

------------------------------ Files Modified File Version Key Changes AlphaTabRenderer.tsx V97.26 Scroll offsets, safe-area padding, aggressive orientation handling ------------------------------ Testing Checklist - Cursor stays visible (not behind Dynamic Island) during playback - Track name fully visible - Cursor positioned ~1 inch from left edge (like Songsterr) - Smooth cursor movement (no jumpy scrolling) - Portrait → Landscape: Single row horizontal layout - Landscape → Portrait: Multi-row page layout - Staff at correct position after rotation (bottom in landscape) - Multiple rapid rotations handled correctly

------------------------------ Future Considerations 1. *Custom Cursor:* Plan to implement custom designed cursor for visual appeal (will deactivate default cursor) 2. *Custom Scroll Container:* May implement container with CSS safe-area insets as dedicated scroll element 3. *Fine-tune 45% offset:* Current setting works but could be adjusted based on user feedback On Thu, Dec 18, 2025 at 3:48 PM Brett Bolzenthal ***@***.***> wrote:

https://drive.google.com/file/d/1VIWRZTtL2O4jtGN7-Kns4Mq4lrE2exM5/view?usp=drivesdk https://youtube.com/shorts/9JDgG0daPec?si=OLchUGALmfoSF_Ii My apologies, the previous image I attached was showing the issue. This is a better illustration. For everyone that currently uses AlphaTab on Mobile App or Mobile devices in this case iPhone. By default the way that AlphaTab is set up … the cursor is hiding behind that black box that is always at the top of the screen or in this case the left edge in the horizontal view. The Cursor should either by fixed by default of AlphaTab at .30 or whatever it would need to be so it stays away from that black box or Dynamic Island as they call it on the iPhones. I am going to check again the article docs you shared and see if that changes anything, but so far it seems that this may be a bug or something that cannot be resolved without using a custom set up. The auto-scroll right now moves one measure at a time (as we know) instead of a steady continuous scroll. On Thu, Dec 18, 2025 at 6:02 AM Daniel Kuschny ***@***.***> wrote: > Can you try to rephrase more precisely what is the current and your > expected behavior? I think I don't understand your problem. If the device > has additional "overlays" or "cut-outs" its something you have to handle in > our app to place alphaTab accordingly. The screenshot doesn't show me > anything regarding this iPhone dynamic islands. > > The scroll offset is accounted during scrolling to leave the configured > space left or on top. If there is an "overlay" or invisible section over > the browser window, there is nothing alphaTab can do. In such a case you > should scale down the viewport in that case so that the right edge of the > scroll element is on the left edge of any overlay. > > You can change from "body" scrolling to a custom scrollable (overflow: > auto) element: > https://alphatab.net/docs/reference/settings/player/scrollelement > > — > Reply to this email directly, view it on GitHub > <#2440 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/BNLESQF5GAEATJBYHWWA4O34CKXXDAVCNFSM6AAAAACPMXHGM2VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKMRYHE4DKNQ> > . > You are receiving this because you authored the thread.Message ID: > ***@***.***> >

[Danielku15]

Thanks for sharing the video and explanation. I had some assumptions on what you might be talking about but now it's clear.

Long story short you have currently options like this:

1. https://jsfiddle.net/danielku15/tmfc8z1h/

You can apply an additional staff padding to shift the content to start after the dynamic iland. Then additionally you supply the scrollOffsetX to also fit the desired position.

In this sample I use firstStaffPaddingLeft because I noticed systemLabelPaddingLeft is not applied when there is no label rendered (#2442). But it still looks ok for now.

There are no official APIs to get the dynamic island info. But you could try to rely on APIs like simple device detection through the user agent or safe-area-inset. Maybe there are libs in the market to help there. Then apply the paddings and offsets to alphaTab.

2. https://jsfiddle.net/danielku15/a85fb7rp/

Resize the scroll container which contains alphaTab. You could adjust your UI further to utilize the space with UI controls. In landscape mode users are likely happy to have more height in the viewport anyhow. More a UI/UX topic to think about.

[Danielku15]

@AvaTheArchitect You might want to start fiddling with the new "smooth" scrolling mode (new version will be published this night by github actions).

#2371 (comment)

brave_PucOpOikIQ.mp4

[AvaTheArchitect]

So excited! Thank you! Thank you! Thank you!

…

On Sat, Dec 20, 2025 at 9:38 AM Daniel Kuschny ***@***.***> wrote: @AvaTheArchitect <https://github.com/AvaTheArchitect> You might want to start fiddling with the new "smooth" scrolling mode (new version will be published this night by github actions). #2371 (comment) <#2371 (comment)> https://github.com/user-attachments/assets/d10c76c1-ebf8-42ad-a946-fa0124c146ab — Reply to this email directly, view it on GitHub <#2440 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNLESQFTBHCHBSQKIWNYY634CWCQTAVCNFSM6AAAAACPMXHGM2VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKMZQGY3TINI> . You are receiving this because you were mentioned.Message ID: ***@***.***>