Using a ScrollView
ScrollView shows one authored view tree inside a smaller viewport. It is a good fit for heterogeneous, page-like content such as a long detail screen, settings page, or form that extends across several viewport heights. When a child receives focus, the content moves according to the configured horizontal and vertical alignment.
ScrollView renders its full child tree. Use CollectionView for rails, grids, EPGs, season or episode lists, remote data, and other content collections. CollectionView virtualizes and pools its rows and cells and can use AppConfig fragments for reusable, separately updated presentation.
Choose the Right Surface
| Content | Use |
|---|---|
| A few similar buttons, icons, or badges | Repeater |
| One heterogeneous page that is larger than its viewport | ScrollView |
| A data-driven list, rail, grid, EPG, season list, or episode list | CollectionView |
CollectionView is also suitable for detail screens and form-like experiences when their sections are naturally data-driven rows or items.
Focus and Viewport Setup
The common pattern is:
ScrollView([
VGroup(items.map((item, index) =>
Button({ text: item.title })
.canReceiveFocus(true)
.isInitialFocus(index === 0)
)).itemSpacing(16)
])
.id('settingsScroll')
.viewportWidth(700)
.viewportHeight(600)
.verticalAlignment(ScrollVerticalAlignment.Floating)
.horizontalAlignment(ScrollHorizontalAlignment.None)
.animationDuration(250);
Floating keeps the focused child visible while avoiding unnecessary motion when it is already inside the viewport. Center, Bottom, Right, CustomPosition, and callback alignments are useful for more controlled layouts.
Programmatic Scrolling
Resolve the rendered ScrollViewView when you need an imperative scroll. Use scrollTo when you know the target translation, and animateToChild when you have a rendered child view.
const scrollView = this.getSubView<ScrollViewView>('settingsScroll', true);
scrollView?.scrollTo([0, -320], 250);
const advancedSettings = this.getSubView('advancedSettings', true);
if (scrollView && advancedSettings) {
scrollView.animateToChild(advancedSettings, 250);
}
The declarative scrollToChild(...) state is also available when the target is already part of the authored view tree. Call reset() when reusing a ScrollView or returning it to the initial position.
Placement Rules
Use ScrollView in normal screen trees, including detail and form screens.
Do not embed ScrollView, ScrollContainer, or Repeater inside a CollectionView cell, custom cell, or supplementary/header view. Model nested content as CollectionView rows and cells instead. This keeps focus, scrolling, recycling, and fragment updates under one collection owner.
Pointer Scrolling on Web
Web mouse and touch adapters can scroll ScrollView with wheel and drag gestures. The adapters convert browser pixels into Hosanna design-space coordinates, then update the internal scroll position. Keep layout and hit testing in design points; do not compensate for browser DPI or CSS scale in app code.