Skip to main content

Using a ScrollView

ScrollView shows a group of views inside a smaller viewport. It is focus-aware: when a child receives focus, the scrollable content moves according to the configured horizontal and vertical alignment.

ScrollView vs CollectionView

ScrollView renders all of its children. Use it for forms, settings screens, and moderate static content. Use CollectionView for large rails, grids, remote data, and lists that need virtualization.

Basic Example​

The Basics Using A Scrollview

@view('TheBasicsUsingAScrollview')
export class TheBasicsUsingAScrollviewView extends BaseExampleScreenView<TheBasicsUsingAScrollviewState> {

  protected getViews(): ViewStruct<ViewState>[] {

    // --- edit below ---

    return [
      ScrollView([
        VGroup(
          Array(20).fill(0).map((_, i) =>
            Rectangle({
              id: `rectangle-${i}`,
              color: i % 2 === 0 ? '#4A90E2' : '#50E3C2',
              height: 100,
              width: 200,
            })
              .canReceiveFocus(true)
              .isInitialFocus(i === 0)

          )
        ).itemSpacing(20)
      ])
        .viewportHeight(300)
        .viewportWidth(200)
        .verticalAlignment(ScrollHorizontalAlignment.Floating)
    ]

    // --- edit above ---
  }
}

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​

Use scrollTo when you know the target translation, and scrollToChild or animateToChild when you have a child view.

this.getSubView<ScrollViewView>('settingsScroll')?.scrollTo([0, -320], 250);

ScrollView([...])
  .scrollToChild(this.getSubView('advancedSettings'))
  .animationDuration(250);

Call reset() when reusing a ScrollView or returning it to the top-left initial position.

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.

Learn More​