.NET MAUI Documentation

ScrollView in .NET MAUI

The ScrollView is a layout control that enables content to be scrolled when it exceeds the bounds of the screen. It can scroll its content horizontally or vertically, and it supports two scroll modes: automatic and always.

Overview

The ScrollView is a common UI element in mobile and desktop applications, allowing users to view content that doesn't fit within the visible viewport. In .NET MAUI, it provides a simple yet effective way to manage overflow content.

Key Features

  • Orientation: Can scroll content horizontally or vertically.
  • Scroll Modes: Supports automatic scrolling (scrollbars appear when needed) and always visible scrollbars.
  • Single Child: The ScrollView can only contain a single child element. If you need to display multiple elements that should scroll together, you should arrange them within a layout container (like a StackLayout or Grid) and then place that container as the single child of the ScrollView.
  • Scroll Indicators: The visibility of scroll indicators can be controlled.

Usage

Basic Vertical Scrolling

To create a vertical ScrollView, simply place your content inside it. By default, ScrollView attempts to scroll vertically if its content is larger than its allocated space.

XAML Example

<ScrollView>
    <VerticalStackLayout>
        <!-- Content that might exceed screen height -->
        <Label Text="Item 1" FontSize="24" />
        <Label Text="Item 2" FontSize="24" />
        <Label Text="Item 3" FontSize="24" />
        <Label Text="Item 4" FontSize="24" />
        <Label Text="Item 5" FontSize="24" />
        <Label Text="Item 6" FontSize="24" />
        <Label Text="Item 7" FontSize="24" />
        <Label Text="Item 8" FontSize="24" />
        <Label Text="Item 9" FontSize="24" />
        <Label Text="Item 10" FontSize="24" />
    </VerticalStackLayout>
</ScrollView>

Horizontal Scrolling

To enable horizontal scrolling, set the Orientation property to HorizontalOptions.Start (which implicitly means horizontal scrolling). You'll typically use a HorizontalStackLayout within a horizontal ScrollView.

XAML Example

<ScrollView Orientation="Horizontal">
    <HorizontalStackLayout>
        <!-- Content that might exceed screen width -->
        <Image Source="icon1.png" WidthRequest="150" HeightRequest="150" />
        <Image Source="icon2.png" WidthRequest="150" HeightRequest="150" />
        <Image Source="icon3.png" WidthRequest="150" HeightRequest="150" />
        <Image Source="icon4.png" WidthRequest="150" HeightRequest="150" />
    </HorizontalStackLayout>
</ScrollView>
Placeholder for Horizontal Scroll View Example

Properties

Orientation

Defines the scrolling direction of the ScrollView. Can be set to Vertical (default) or Horizontal.

IsScrollChainingEnabled

When set to true (default), allows the scroll gesture to propagate to parent or child elements if the ScrollView reaches its scroll limit. This is useful for nested scroll views.

IsClippedToBounds

Determines if the content is clipped to the bounds of the ScrollView. Default is true.

Scrolled Event

Fires when the scroll position of the ScrollView changes. The event handler receives a ScrolledEventArgs object containing the ScrollX and ScrollY values.

Best Practices

  • Ensure your content within the ScrollView is properly laid out using appropriate container elements.
  • Avoid excessively long or wide content that might lead to a poor user experience.
  • Consider performance implications for very large amounts of scrollable content. Techniques like virtualization might be necessary for extreme cases, though ScrollView itself doesn't offer built-in virtualization.

The ScrollView is a fundamental component for creating responsive and user-friendly interfaces in .NET MAUI, ensuring that all your content is accessible regardless of screen size.