Syncfusion Maui Parallax View

Implementing Syncfusion .NET MAUI Parallax View

The Syncfusion .NET MAUI Parallax View (SfParallaxView) provides a visually engaging way to create depth and motion in your applications by scrolling background elements at a different speed than foreground elements. The control binds a scrollable foreground element (Source) to a background element (Content) and moves the background at a varying speed to create a parallax effect.

When to Use This Skill

Use this skill when you need to:

• Create parallax scrolling effects where background images or views move slower than the foreground content
• Add visual depth to scrollable content like lists, articles, or image galleries
• Implement hero sections with parallax backgrounds for engaging user interfaces
• Bind ScrollView or ListView with background elements that respond to scroll events
• Create custom scrollable controls that support parallax effects using the IParallaxView interface
• Build immersive UIs with dynamic background animations tied to scroll position
• Enhance user experience with smooth parallax transitions in vertical or horizontal orientations

Component Overview

SfParallaxView creates a layered scrolling experience with:

• Content: Background view (Image, StackLayout, or any view) that moves with parallax effect
• Source: Foreground scrollable view (ScrollView, ListView, or custom IParallaxView controls)
• Speed: Customizable scroll speed for the background (0.0 to 1.0)
• Orientation: Support for both vertical and horizontal parallax scrolling

The background Content automatically stretches to match the Source size, ensuring seamless visual integration.

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installing Syncfusion.Maui.ParallaxView NuGet package
• Namespace registration in XAML and C#
• Basic SfParallaxView initialization
• Setting the Content property with background views
• Supported content types (Image, StackLayout, Grid, etc.)
• Basic XAML and C# implementation examples

Source Binding and Integration

📄 Read: references/source-binding.md

• Understanding the Source property and IParallaxView interface
• Binding ScrollView to create basic parallax effects
• Integrating Syncfusion ListView with parallax backgrounds
• Complete examples with ViewModels and data binding
• Content auto-stretch behavior to match Source size
• Known issues and workarounds (Android image sizing)
• GitHub sample links for working examples

Customization Options

📄 Read: references/customization.md

• Speed property to control parallax scroll intensity
• Speed values and their visual effects (0.0 = no movement, 1.0 = same speed)
• Orientation property for vertical or horizontal parallax
• Matching Source control orientation for proper effect
• XAML and C# configuration examples
• Performance considerations for smooth scrolling

Custom Controls Support

📄 Read: references/custom-controls.md

• Implementing IParallaxView interface for custom controls
• ScrollableContentSize property for total content size
• Scrolling event with ParallaxScrollingEventArgs
• ScrollX, ScrollY, and CanAnimate parameters
• Complete CustomListView implementation example
• MeasureOverride for dynamic size calculation
• Integration patterns for custom scrollable controls

Custom Controls Support

The Syncfusion .NET MAUI Parallax View supports custom scrollable controls beyond the built-in ScrollView and ListView. This guide explains how to implement the IParallaxView interface to enable parallax effects with any custom scrollable control.

When to Use Custom Controls

Use custom controls with parallax when you need to:

• Integrate third-party scrollable controls not natively supported by SfParallaxView
• Create custom scrolling behaviors with specific performance or interaction requirements
• Build specialized UI components like custom carousels, scrollable grids, or infinite scrollers
• Extend existing controls to support parallax without modifying the SfParallaxView component

The built-in ScrollView and SfListView already implement IParallaxView, so use custom controls only when these don't meet your needs.

IParallaxView Interface

The IParallaxView interface from Syncfusion.Maui.Core provides the contract that enables any control to work with SfParallaxView.

Interface Definition

using Syncfusion.Maui.Core;

public interface IParallaxView
{
    /// <summary>
    /// Gets or sets the total size of the scrollable content.
    /// This represents the entire scrollable area, not just the visible viewport.
    /// </summary>
    Size ScrollableContentSize { get; set; }
    
    /// <summary>
    /// Event raised when scrolling occurs in the control.
    /// Provides scroll position information to the SfParallaxView.
    /// </summary>
    event EventHandler<ParallaxScrollingEventArgs> Scrolling;
}

Interface Members

ScrollableContentSize Property

Purpose: Represents the total scrollable content size (not just the visible area).

Type: System.Drawing.Size or Microsoft.Maui.Graphics.Size

When to Set:

• In the control's constructor (if size is known)
• In MeasureOverride or OnSizeAllocated (for dynamic sizing)
• When content is loaded or changed

Example:

public Size ScrollableContentSize { get; set; }

public CustomScrollView()
{
    // Set total scrollable size
    this.ScrollableContentSize = new Size(400, 2000); // Width: 400, Height: 2000
}

Scrolling Event

Purpose: Notifies SfParallaxView when the control scrolls, providing position information.

Event Args: ParallaxScrollingEventArgs

When to Raise: Whenever the control's scroll position changes.

Example:

public event EventHandler<ParallaxScrollingEventArgs> Scrolling;

private void OnScrollChanged(double scrollX, double scrollY)
{
    // Raise the event to notify SfParallaxView
    Scrolling?.Invoke(this, new ParallaxScrollingEventArgs(scrollX, scrollY, false));
}

ParallaxScrollingEventArgs

The event args class that communicates scroll information to the SfParallaxView.

Properties

Constructor

public ParallaxScrollingEventArgs(double scrollX, double scrollY, bool canAnimate)
{
    ScrollX = scrollX;
    ScrollY = scrollY;
    CanAnimate = canAnimate;
}

Parameters:

• scrollX: The X position of the finished scroll (left edge of viewport)
• scrollY: The Y position of the finished scroll (top edge of viewport)
• canAnimate: Set to true for smooth animated transitions, false for immediate updates

Typical Usage:

// For immediate updates (most common)
new ParallaxScrollingEventArgs(e.ScrollX, e.ScrollY, false)

// For animated transitions
new ParallaxScrollingEventArgs(e.ScrollX, e.ScrollY, true)

Complete Custom Control Implementation

Here's a complete example of implementing a custom ListView with parallax support:

CustomListView Implementation

using Syncfusion.Maui.Core;
using System.Collections;

namespace ParallaxViewCustomControl
{
    /// <summary>
    /// Custom ListView that implements IParallaxView for parallax scrolling support.
    /// </summary>
    public class CustomListView : ListView, IParallaxView
    {
        // IParallaxView interface members
        public Size ScrollableContentSize { get; set; }
        public event EventHandler<ParallaxScrollingEventArgs>? Scrolling;
        
        public CustomListView()
        {
            // Subscribe to the ListView's built-in Scrolled event
            this.Scrolled += CustomListView_Scrolled;
        }
        
        /// <summary>
        /// Handle scrolling and notify the SfParallaxView
        /// </summary>
        private void CustomListView_Scrolled(object? sender, ScrolledEventArgs e)
        {
            if (sender is ListView listView && Scrolling != null)
            {
                // Raise the Scrolling event with current scroll position
                // CanAnimate = false for immediate updates (better performance)
                Scrolling.Invoke(this, new ParallaxScrollingEventArgs(
                    e.ScrollX, 
                    e.ScrollY, 
                    false));
            }
        }
        
        /// <summary>
        /// Override measure to calculate and set the total scrollable content size
        /// </summary>
        protected override Size MeasureOverride(double widthConstraint, double heightConstraint)
        {
            var minimumSize = new Size(40, 40);
            Size request = Size.Zero;
            
            // Calculate total content size for uniform row heights
            if (ItemsSource is IList list && 
                HasUnevenRows == false && 
                RowHeight > 0 && 
                !IsGroupingEnabled)
            {
                // Total height = number of items × row height
                request = new Size(widthConstraint, list.Count * RowHeight);
            }
            
            // Set the scrollable content size for parallax calculations
            this.ScrollableContentSize = new SizeRequest(request, minimumSize);
            
            return base.MeasureOverride(widthConstraint, heightConstraint);
        }
        
        /// <summary>
        /// Clean up event subscriptions
        /// </summary>
        protected override void OnHandlerChanged()
        {
            base.OnHandlerChanged();
            
            if (Handler == null)
            {
                this.Scrolled -= CustomListView_Scrolled;
            }
        }
    }
}

Using the Custom Control

XAML:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:parallax="clr-namespace:Syncfusion.Maui.ParallaxView;assembly=Syncfusion.Maui.ParallaxView"
    xmlns:local="clr-namespace:ParallaxViewCustomControl"
    x:Class="ParallaxViewCustomControl.MainPage">
    
    <Grid>
        <!-- Parallax View with custom control as Source -->
        <parallax:SfParallaxView Source="{x:Reference customListView}" x:Name="parallaxView">
            <parallax:SfParallaxView.Content>
                <Image Source="{Binding BackgroundImage}" 
                       BackgroundColor="Transparent"
                       HorizontalOptions="Fill" 
                       VerticalOptions="Fill" 
                       Aspect="AspectFill" />
            </parallax:SfParallaxView.Content>
        </parallax:SfParallaxView>
        
        <!-- Custom ListView -->
        <local:CustomListView x:Name="customListView"
                              ItemsSource="{Binding Items}"
                              BackgroundColor="Transparent"
                              RowHeight="100"
                              HasUnevenRows="False">
            <local:CustomListView.ItemTemplate>
                <DataTemplate>
                    <ViewCell>
                        <Grid Padding="15" BackgroundColor="#80000000">
                            <Label Text="{Binding Title}" 
                                   FontSize="18" 
                                   TextColor="White" />
                        </Grid>
                    </ViewCell>
                </DataTemplate>
            </local:CustomListView.ItemTemplate>
        </local:CustomListView>
    </Grid>
</ContentPage>

C# Code-Behind:

using Syncfusion.Maui.ParallaxView;

namespace ParallaxViewCustomControl
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            InitializeComponent();
            BindingContext = new ParallaxViewModel();
        }
    }
    
    public class ParallaxViewModel
    {
        public ImageSource BackgroundImage { get; set; }
        public List<ItemData> Items { get; set; }
        
        public ParallaxViewModel()
        {
            BackgroundImage = ImageSource.FromFile("background.jpg");
            
            Items = new List<ItemData>
            {
                new ItemData { Title = "Item 1" },
                new ItemData { Title = "Item 2" },
                new ItemData { Title = "Item 3" },
                new ItemData { Title = "Item 4" },
                new ItemData { Title = "Item 5" },
                // Add more items...
            };
        }
    }
    
    public class ItemData
    {
        public string Title { get; set; }
    }
}

Advanced Custom Control Example

Here's a more advanced custom control with dynamic content size:

using Syncfusion.Maui.Core;

namespace ParallaxViewCustomControl
{
    public class CustomScrollableView : ContentView, IParallaxView
    {
        private ScrollView _scrollView;
        
        public Size ScrollableContentSize { get; set; }
        public event EventHandler<ParallaxScrollingEventArgs>? Scrolling;
        
        public CustomScrollableView()
        {
            // Create internal ScrollView
            _scrollView = new ScrollView
            {
                BackgroundColor = Colors.Transparent
            };
            
            _scrollView.Scrolled += OnScrollViewScrolled;
            
            // Set as content
            Content = _scrollView;
        }
        
        /// <summary>
        /// Set the scrollable content
        /// </summary>
        public View ScrollableContent
        {
            get => _scrollView.Content;
            set
            {
                _scrollView.Content = value;
                UpdateScrollableContentSize();
            }
        }
        
        private void OnScrollViewScrolled(object sender, ScrolledEventArgs e)
        {
            // Notify parallax view of scroll changes
            Scrolling?.Invoke(this, new ParallaxScrollingEventArgs(
                e.ScrollX, 
                e.ScrollY, 
                false));
        }
        
        private void UpdateScrollableContentSize()
        {
            if (_scrollView.Content != null)
            {
                // Measure the content
                var contentSize = _scrollView.Content.Measure(
                    double.PositiveInfinity, 
                    double.PositiveInfinity);
                
                ScrollableContentSize = contentSize.Request;
            }
        }
        
        protected override void OnSizeAllocated(double width, double height)
        {
            base.OnSizeAllocated(width, height);
            UpdateScrollableContentSize();
        }
    }
}

Implementation Checklist

When implementing IParallaxView for custom controls, ensure you:

• ✅ Implement ScrollableContentSize property - Store and update the total content size
• ✅ Implement Scrolling event - Declare the event with correct signature
• ✅ Calculate content size accurately - In constructor, MeasureOverride, or OnSizeAllocated
• ✅ Raise Scrolling event on scroll changes - Hook into native scroll events
• ✅ Pass correct scroll positions - ScrollX and ScrollY represent viewport position
• ✅ Use CanAnimate appropriately - Usually false for better performance
• ✅ Handle cleanup - Unsubscribe from events when control is disposed
• ✅ Test on all platforms - Verify behavior on Android, iOS, Windows, macOS

Sample Repository

For complete working examples of custom controls with parallax:

GitHub Repository: MAUI Parallax View Sample Demos

What you'll find:

• CustomListView with IParallaxView implementation
• Integration examples with XAML and C#
• ViewModels with sample data
• MeasureOverride patterns for dynamic sizing
• Event handler best practices

Common Implementation Patterns

Pattern 1: Wrapping Existing ScrollView

public class CustomScrollWrapper : ContentView, IParallaxView
{
    private ScrollView _scrollView;
    
    public Size ScrollableContentSize { get; set; }
    public event EventHandler<ParallaxScrollingEventArgs> Scrolling;
    
    public CustomScrollWrapper()
    {
        _scrollView = new ScrollView();
        _scrollView.Scrolled += (s, e) => 
            Scrolling?.Invoke(this, new ParallaxScrollingEventArgs(e.ScrollX, e.ScrollY, false));
        Content = _scrollView;
    }
}

Pattern 2: Extending CollectionView

public class ParallaxCollectionView : CollectionView, IParallaxView
{
    public Size ScrollableContentSize { get; set; }
    public event EventHandler<ParallaxScrollingEventArgs> Scrolling;
    
    public ParallaxCollectionView()
    {
        Scrolled += (s, e) => 
            Scrolling?.Invoke(this, new ParallaxScrollingEventArgs(e.ScrollX, e.ScrollY, false));
    }
}

Pattern 3: Custom Grid with Scrolling

public class ScrollableGrid : Grid, IParallaxView
{
    private ScrollView _internalScroll;
    
    public Size ScrollableContentSize { get; set; }
    public event EventHandler<ParallaxScrollingEventArgs> Scrolling;
    
    // Implementation details...
}

Troubleshooting

Issue: Scrolling event not firing

Cause: Event not properly subscribed or raised Solution: Verify you're subscribing to the underlying control's scroll event and raising the Scrolling event with correct parameters

Issue: ScrollableContentSize is zero

Cause: Content size not calculated or set Solution: Calculate size in MeasureOverride or OnSizeAllocated. For dynamic content, recalculate when content changes

Issue: Parallax effect jerky or inconsistent

Cause: Incorrect scroll position values Solution: Ensure ScrollX/ScrollY represent the actual viewport position, not delta values. Use CanAnimate=false for smoother performance

Issue: Memory leaks

Cause: Event subscriptions not cleaned up Solution: Unsubscribe from events in OnHandlerChanged or Dispose methods

Next Steps

• [Getting Started](getting-started.md) - Review basic parallax setup
• [Source Binding](source-binding.md) - Learn about built-in control integration
• [Customization](customization.md) - Adjust speed and orientation settings

Best Practices

1. Use built-in controls when possible - ScrollView and SfListView already work with parallax 2. Calculate size accurately - Incorrect ScrollableContentSize causes positioning issues 3. Optimize event handling - Raise Scrolling event only when position changes 4. Test performance - Custom controls may impact scroll performance 5. Document assumptions - Clearly document expected content types and sizes 6. Handle edge cases - Empty content, single item, very large content 7. Platform-specific testing - Verify behavior on all target platforms

Customization Options

The Syncfusion .NET MAUI Parallax View provides powerful customization options to fine-tune the parallax effect and adapt it to different UI designs and orientations.

Speed Customization

The Speed property is the primary way to control the intensity and behavior of the parallax effect. It determines how fast the background Content scrolls relative to the foreground Source.

Understanding Speed Values

The Speed property accepts a double value between 0.0 and 1.0:

Default: 0.5 (50% of foreground scroll speed)

Recommended range: 0.3 - 0.6 for most applications

Setting Speed in XAML

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:parallax="clr-namespace:Syncfusion.Maui.ParallaxView;assembly=Syncfusion.Maui.ParallaxView"
    xmlns:list="clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView"
    x:Class="ParallaxViewDemo.MainPage">
    
    <Grid>
        <!-- Subtle parallax with Speed=0.4 -->
        <parallax:SfParallaxView Source="{x:Reference listView}" 
                                  x:Name="parallaxView" 
                                  Speed="0.4">
            <parallax:SfParallaxView.Content>
                <Image Source="{Binding BackgroundImage}" 
                       BackgroundColor="Transparent"
                       HorizontalOptions="Fill" 
                       VerticalOptions="Fill" 
                       Aspect="AspectFill" />
            </parallax:SfParallaxView.Content>
        </parallax:SfParallaxView>
        
        <list:SfListView x:Name="listView" 
                         ItemsSource="{Binding Items}" 
                         BackgroundColor="Transparent"
                         ItemSize="100">
            <!-- ItemTemplate here -->
        </list:SfListView>
    </Grid>
</ContentPage>

Setting Speed in C#

using Syncfusion.Maui.ParallaxView;
using Syncfusion.Maui.ListView;

namespace ParallaxViewDemo
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            InitializeComponent();
            
            ParallaxViewModel viewModel = new ParallaxViewModel();
            BindingContext = viewModel;
            
            // Create parallax view with custom speed
            SfParallaxView parallax = new SfParallaxView
            {
                Speed = 0.4 // Set custom speed
            };
            
            // Set background image
            Image backgroundImage = new Image
            {
                Source = viewModel.BackgroundImage,
                BackgroundColor = Colors.Transparent,
                HorizontalOptions = LayoutOptions.Fill,
                VerticalOptions = LayoutOptions.Fill,
                Aspect = Aspect.AspectFill
            };
            parallax.Content = backgroundImage;
            
            // Create ListView
            SfListView listView = new SfListView
            {
                ItemsSource = viewModel.Items,
                BackgroundColor = Colors.Transparent,
                ItemSize = 100
            };
            
            // Bind ListView as Source
            parallax.Source = listView;
            
            // Add to grid
            Grid grid = new Grid();
            grid.Children.Add(parallax);
            grid.Children.Add(listView);
            
            this.Content = grid;
        }
    }
}

Speed Selection Guidelines

For Hero Sections (Speed = 0.3 - 0.4):

• Subtle, professional look
• Background barely moves, creating depth without distraction
• Ideal for marketing pages, landing screens

For Content Readers (Speed = 0.4 - 0.5):

• Balanced parallax effect
• Adds visual interest without overwhelming text
• Good for article readers, blog posts

For Image Galleries (Speed = 0.5 - 0.7):

• More pronounced parallax
• Highlights the scrolling motion
• Works well for visual-heavy content

For Immersive Experiences (Speed = 0.7 - 0.8):

• Strong parallax effect
• Background moves almost as fast as foreground
• Use sparingly for dramatic effect

Dynamic Speed Changes

You can change the speed at runtime based on user preferences or context:

// Adjust speed based on user preference
public void SetParallaxIntensity(string intensity)
{
    switch (intensity)
    {
        case "subtle":
            parallaxView.Speed = 0.3;
            break;
        case "normal":
            parallaxView.Speed = 0.5;
            break;
        case "intense":
            parallaxView.Speed = 0.7;
            break;
        case "none":
            parallaxView.Speed = 0.0; // Disable parallax
            break;
    }
}

Orientation Customization

The Orientation property controls the scroll direction of the parallax effect. By default, it's set to Vertical, but you can change it to Horizontal for side-scrolling parallax experiences.

Available Orientations

• Vertical (default) - Top-to-bottom scrolling
• Horizontal - Left-to-right scrolling

Important: The Source control's orientation must match the ParallaxView's orientation for the effect to work correctly.

Horizontal Parallax Example

XAML:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:parallax="clr-namespace:Syncfusion.Maui.ParallaxView;assembly=Syncfusion.Maui.ParallaxView"
    xmlns:list="clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView"
    x:Class="ParallaxViewDemo.MainPage">
    
    <Grid>
        <!-- Horizontal Parallax View -->
        <parallax:SfParallaxView Source="{x:Reference listView}" 
                                  x:Name="parallaxView" 
                                  Orientation="Horizontal"
                                  Speed="0.5">
            <parallax:SfParallaxView.Content>
                <Image Source="{Binding BackgroundImage}" 
                       BackgroundColor="Transparent"
                       HorizontalOptions="Fill" 
                       VerticalOptions="Fill" 
                       Aspect="AspectFill" />
            </parallax:SfParallaxView.Content>
        </parallax:SfParallaxView>
        
        <!-- Horizontal ListView (Orientation MUST match) -->
        <list:SfListView x:Name="listView" 
                         Orientation="Horizontal"
                         ItemsSource="{Binding Items}" 
                         BackgroundColor="Transparent"
                         ItemSize="200">
            <list:SfListView.ItemTemplate>
                <DataTemplate>
                    <ViewCell>
                        <StackLayout Padding="10" WidthRequest="200">
                            <Image Source="{Binding ItemImage}" 
                                   HeightRequest="150" 
                                   Aspect="AspectFill" />
                            <Label Text="{Binding Name}" 
                                   FontSize="16" 
                                   TextColor="White" />
                        </StackLayout>
                    </ViewCell>
                </DataTemplate>
            </list:SfListView.ItemTemplate>
        </list:SfListView>
    </Grid>
</ContentPage>

C#:

using Syncfusion.Maui.ParallaxView;
using Syncfusion.Maui.ListView;

namespace ParallaxViewDemo
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            InitializeComponent();
            
            ParallaxViewModel viewModel = new ParallaxViewModel();
            BindingContext = viewModel;
            
            // Create horizontal parallax view
            SfParallaxView parallax = new SfParallaxView
            {
                Orientation = Syncfusion.Maui.ParallaxView.Orientation.Horizontal,
                Speed = 0.5
            };
            
            // Set background
            Image backgroundImage = new Image
            {
                Source = viewModel.BackgroundImage,
                BackgroundColor = Colors.Transparent,
                HorizontalOptions = LayoutOptions.Fill,
                VerticalOptions = LayoutOptions.Fill,
                Aspect = Aspect.AspectFill
            };
            parallax.Content = backgroundImage;
            
            // Create horizontal ListView
            SfListView listView = new SfListView
            {
                Orientation = ItemsLayoutOrientation.Horizontal,
                ItemsSource = viewModel.Items,
                BackgroundColor = Colors.Transparent,
                ItemSize = 200
            };
            
            // Bind ListView as Source
            parallax.Source = listView;
            
            // Add to grid
            Grid grid = new Grid();
            grid.Children.Add(parallax);
            grid.Children.Add(listView);
            
            this.Content = grid;
        }
    }
}

Horizontal ScrollView Example

For simpler horizontal scrolling without a list:

<Grid>
    <parallax:SfParallaxView Source="{x:Reference scrollView}" 
                              Orientation="Horizontal"
                              Speed="0.4">
        <parallax:SfParallaxView.Content>
            <Image Source="wide_background.jpg" Aspect="AspectFill" />
        </parallax:SfParallaxView.Content>
    </parallax:SfParallaxView>
    
    <ScrollView x:Name="scrollView" 
                Orientation="Horizontal" 
                BackgroundColor="Transparent">
        <HorizontalStackLayout Spacing="20" Padding="20">
            <Frame WidthRequest="300" HeightRequest="400">
                <Label Text="Card 1" />
            </Frame>
            <Frame WidthRequest="300" HeightRequest="400">
                <Label Text="Card 2" />
            </Frame>
            <Frame WidthRequest="300" HeightRequest="400">
                <Label Text="Card 3" />
            </Frame>
        </HorizontalStackLayout>
    </ScrollView>
</Grid>

Combining Speed and Orientation

You can combine both properties for maximum customization:

<!-- Fast horizontal parallax -->
<parallax:SfParallaxView Source="{x:Reference scrollView}" 
                          Orientation="Horizontal"
                          Speed="0.7">
    <parallax:SfParallaxView.Content>
        <Image Source="panorama.jpg" Aspect="AspectFill" />
    </parallax:SfParallaxView.Content>
</parallax:SfParallaxView>

// Slow vertical parallax
var parallax = new SfParallaxView
{
    Orientation = Syncfusion.Maui.ParallaxView.Orientation.Vertical,
    Speed = 0.3,
    Content = new Image 
    { 
        Source = "background.jpg", 
        Aspect = Aspect.AspectFill 
    }
};

Performance Considerations

Optimizing for Smooth Scrolling

Image Optimization:

• Use appropriately sized images (don't load 4K images for mobile displays)
• Compress images to reduce memory usage
• Consider using cached images for better performance

Speed Selection:

• Lower speed values (0.3-0.5) generally perform better
• Higher speeds require more frequent background updates

Content Complexity:

• Keep Content views simple (avoid complex layouts with many nested views)
• Single images perform better than complex StackLayouts
• Avoid animations within the Content view

Testing Recommendations

• Test on low-end devices to ensure smooth scrolling
• Monitor frame rates during scrolling
• Test with different image sizes and resolutions
• Verify performance on both Android and iOS platforms

Common Customization Patterns

Subtle Background Motion

Speed = 0.3, Orientation = Vertical

Best for professional apps, news readers, documentation

Standard Parallax Effect

Speed = 0.5, Orientation = Vertical

Best for general use, balanced visual interest

Dramatic Parallax

Speed = 0.7, Orientation = Vertical

Best for visual-heavy apps, galleries, portfolios

Horizontal Carousel

Speed = 0.5, Orientation = Horizontal

Best for image galleries, product showcases

Disable Parallax (Static Background)

Speed = 0.0

Useful for accessibility or user preference settings

Next Steps

• [Custom Controls](custom-controls.md) - Implement IParallaxView for custom scrollable controls
• [Getting Started](getting-started.md) - Review basic setup and installation
• [Source Binding](source-binding.md) - Learn about Source property and control integration

Troubleshooting

Issue: Parallax effect too subtle/strong

Solution: Adjust the Speed property. Start with 0.5 and increment/decrement by 0.1 until desired effect is achieved.

Issue: Horizontal parallax not working

Solution: Ensure both the SfParallaxView.Orientation AND the Source control's orientation are set to Horizontal.

Issue: Laggy scrolling with parallax

Solution: Reduce the Speed value, optimize Content images, or simplify the Content layout structure.

Issue: Background moves at same speed as foreground

Solution: Verify Speed is not set to 1.0. Use values between 0.3-0.7 for visible parallax effect.

Getting Started with Syncfusion .NET MAUI Parallax View

This guide walks you through installing, configuring, and implementing the basic Syncfusion .NET MAUI Parallax View (SfParallaxView) control in your application.

Installation

Step 1: Install the NuGet Package

1. In Solution Explorer, right-click your project and choose Manage NuGet Packages 2. Search for Syncfusion.Maui.ParallaxView 3. Install the latest version of the package 4. Ensure all dependencies are installed correctly and the project is restored

Package Name: Syncfusion.Maui.ParallaxView

Via Package Manager Console:

Install-Package Syncfusion.Maui.ParallaxView

Via .NET CLI:

dotnet add package Syncfusion.Maui.ParallaxView

Step 2: Register the Syncfusion Handler

CRITICAL: The Syncfusion.Maui.Core NuGet is a dependent package for all Syncfusion controls. You MUST register the handler in MauiProgram.cs.

File: MauiProgram.cs

using Syncfusion.Maui.Core.Hosting;

    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            
            // Register Syncfusion Core - REQUIRED!
            builder.ConfigureSyncfusionCore();
            
            builder
                .UseMauiApp<App>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                    fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                });

            return builder.Build();
        }
    }

⚠️ Important: Call ConfigureSyncfusionCore() before Build(). Failure to register the handler will result in runtime errors.

Step 3: Register Namespace

After installing the package, import the namespace in your XAML or C# files.

XAML:

xmlns:parallax="clr-namespace:Syncfusion.Maui.ParallaxView;assembly=Syncfusion.Maui.ParallaxView"

C#:

using Syncfusion.Maui.ParallaxView;

Basic SfParallaxView Initialization

The SfParallaxView control requires two main components: 1. Content - The background view that moves with the parallax effect 2. Source - The foreground scrollable view that drives the parallax motion

XAML Initialization

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:parallax="clr-namespace:Syncfusion.Maui.ParallaxView;assembly=Syncfusion.Maui.ParallaxView"
    x:Class="ParallaxViewDemo.MainPage">
    
    <Grid>
        <parallax:SfParallaxView x:Name="parallaxView" />
    </Grid>
</ContentPage>

C# Initialization

using Syncfusion.Maui.ParallaxView;

namespace ParallaxViewDemo
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            InitializeComponent();
            
            Grid grid = new Grid();
            SfParallaxView parallaxView = new SfParallaxView();
            grid.Children.Add(parallaxView);
            
            this.Content = grid;
        }
    }
}

Adding Content (Background View)

The Content property represents the background view of the parallax view. You can set any kind of view to the Content property, such as Image, StackLayout, Grid, or any custom view.

Setting Image as Content

XAML:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:parallax="clr-namespace:Syncfusion.Maui.ParallaxView;assembly=Syncfusion.Maui.ParallaxView"
    x:Class="ParallaxViewDemo.MainPage">
    
    <Grid>
        <parallax:SfParallaxView x:Name="parallaxView">
            <parallax:SfParallaxView.Content>
                <Image Source="{Binding BackgroundImage}" 
                       BackgroundColor="Transparent"
                       HorizontalOptions="Fill" 
                       VerticalOptions="Fill" 
                       Aspect="AspectFill" />
            </parallax:SfParallaxView.Content>
        </parallax:SfParallaxView>
    </Grid>
</ContentPage>

C#:

using Syncfusion.Maui.ParallaxView;

namespace ParallaxViewDemo
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            InitializeComponent();
            BindingContext = new ParallaxViewModel();
        }
    }
    
    public class ParallaxViewModel
    {
        public ImageSource BackgroundImage { get; set; }
        
        public ParallaxViewModel()
        {
            // Load from resource
            BackgroundImage = ImageSource.FromResource(
                "ParallaxViewDemo.Resources.Images.parallax_bg.jpg", 
                typeof(MainPage).GetTypeInfo().Assembly);
                
            // Or load from file
            // BackgroundImage = ImageSource.FromFile("parallax_bg.jpg");
        }
    }
}

Setting StackLayout as Content

You can use any view as the Content, not just images:

XAML:

<parallax:SfParallaxView x:Name="parallaxView">
    <parallax:SfParallaxView.Content>
        <StackLayout BackgroundColor="#4A90E2" Padding="20">
            <Label Text="Parallax Background" 
                   FontSize="32" 
                   TextColor="White" 
                   HorizontalOptions="Center" 
                   VerticalOptions="Center" />
        </StackLayout>
    </parallax:SfParallaxView.Content>
</parallax:SfParallaxView>

C#:

var parallaxView = new SfParallaxView
{
    Content = new StackLayout
    {
        BackgroundColor = Color.FromArgb("#4A90E2"),
        Padding = new Thickness(20),
        Children =
        {
            new Label
            {
                Text = "Parallax Background",
                FontSize = 32,
                TextColor = Colors.White,
                HorizontalOptions = LayoutOptions.Center,
                VerticalOptions = LayoutOptions.Center
            }
        }
    }
};

Supported Content Types

The Content property accepts any .NET MAUI View, including:

• Image - Most common for parallax backgrounds
• StackLayout - For layered or gradient backgrounds
• Grid - For complex background layouts
• AbsoluteLayout - For positioned background elements
• Frame - For bordered backgrounds with shadows
• Border - For rounded corner backgrounds
• Custom Views - Any custom control inheriting from View

Multiple Elements in Content

Use a container layout to add multiple elements:

<parallax:SfParallaxView.Content>
    <Grid>
        <Image Source="background.jpg" Aspect="AspectFill" />
        <BoxView Color="#80000000" /> <!-- Semi-transparent overlay -->
        <Label Text="Hero Title" 
               FontSize="48" 
               TextColor="White" 
               HorizontalOptions="Center" 
               VerticalOptions="Center" />
    </Grid>
</parallax:SfParallaxView.Content>

Important Notes

Content Size Behavior

The size of the Content view will automatically be stretched to match the size of the Source view. This ensures that:

• The background covers the entire scrollable area
• No gaps appear during scrolling
• The parallax effect works smoothly across all scroll positions

You don't need to manually set the size of the Content - it's handled automatically by the control.

Transparent Foreground

For the parallax effect to be visible, ensure your Source control (ScrollView, ListView, etc.) has a transparent background:

<ScrollView x:Name="scrollView" BackgroundColor="Transparent">
    <!-- Content here -->
</ScrollView>

Without a transparent background, the Source will obscure the Content, and no parallax effect will be visible.

Video Tutorial

For a quick visual guide, watch the official Syncfusion video tutorial: Getting Started with .NET MAUI Parallax View

Next Steps

Now that you have the basic setup:

• [Source Binding](source-binding.md) - Learn how to bind scrollable controls to create the parallax effect
• [Customization](customization.md) - Customize speed and orientation for different effects
• [Custom Controls](custom-controls.md) - Implement IParallaxView for custom scrollable controls

Common Issues

Issue: Parallax effect not visible

Solution: Ensure the Source control has BackgroundColor="Transparent" so the Content is visible through it.

Issue: Content doesn't fill the entire area

Solution: The Content automatically stretches to match the Source size. If this isn't working, ensure your Source control has a defined size.

Issue: NuGet package not found

Solution: Ensure you have the Syncfusion NuGet feed configured or are using the public NuGet.org feed where the package is available.

Source Binding and Integration

The Source property is the key to creating the parallax effect. It represents the foreground scrollable control that drives the parallax motion of the background Content. This guide explains how to bind scrollable controls to create effective parallax experiences.

Understanding the Source Property

The Source property must be set to a scrollable control that implements the IParallaxView interface. When the Source scrolls, the SfParallaxView automatically moves the Content (background) at a different speed based on the Speed property, creating the parallax effect.

Requirements:

• Source must be a scrollable view (has scrolling capability)
• Source must implement IParallaxView interface (or be a built-in supported control)
• Source should have a transparent background for the parallax effect to be visible

Built-in Supported Controls

Syncfusion ParallaxView has built-in support for these controls - no additional configuration needed:

1. .NET MAUI ScrollView - Native MAUI scrollable container 2. Syncfusion ListView (SfListView) - Syncfusion's list control

Both of these controls already implement the IParallaxView interface, so you can bind them directly to the Source property.

IParallaxView Interface

The IParallaxView interface provides the contract for scrollable controls to work with SfParallaxView:

public interface IParallaxView
{
    // Total size of the scrollable content
    Size ScrollableContentSize { get; set; }
    
    // Event raised when scrolling occurs
    event EventHandler<ParallaxScrollingEventArgs> Scrolling;
}

For custom controls, you'll need to implement this interface. See custom-controls.md for details.

ScrollView Integration

The simplest parallax implementation uses .NET MAUI's built-in ScrollView.

Basic ScrollView Example

XAML:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:parallax="clr-namespace:Syncfusion.Maui.ParallaxView;assembly=Syncfusion.Maui.ParallaxView"
    x:Class="ParallaxViewDemo.MainPage">
    
    <Grid>
        <!-- Parallax View with Image Background -->
        <parallax:SfParallaxView Source="{x:Reference scrollView}" x:Name="parallaxView">
            <parallax:SfParallaxView.Content>
                <Image Source="background_image.jpg" 
                       BackgroundColor="Transparent"
                       HorizontalOptions="Fill" 
                       VerticalOptions="Fill" 
                       Aspect="AspectFill" />
            </parallax:SfParallaxView.Content>
        </parallax:SfParallaxView>
        
        <!-- Foreground ScrollView (MUST be transparent) -->
        <ScrollView x:Name="scrollView" BackgroundColor="Transparent">
            <StackLayout Padding="20" Spacing="15">
                <Label Text="Article Title" 
                       FontSize="32" 
                       FontAttributes="Bold" 
                       TextColor="White" />
                <Label Text="Lorem ipsum dolor sit amet, consectetur adipiscing elit..." 
                       FontSize="16" 
                       TextColor="White" />
                <BoxView HeightRequest="500" Color="Transparent" />
                <Label Text="More content here..." 
                       FontSize="16" 
                       TextColor="White" />
                <BoxView HeightRequest="500" Color="Transparent" />
            </StackLayout>
        </ScrollView>
    </Grid>
</ContentPage>

C#:

using Syncfusion.Maui.ParallaxView;

namespace ParallaxViewDemo
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            InitializeComponent();
            
            // Create parallax view
            var parallaxView = new SfParallaxView();
            
            // Set background content
            var backgroundImage = new Image
            {
                Source = "background_image.jpg",
                BackgroundColor = Colors.Transparent,
                HorizontalOptions = LayoutOptions.Fill,
                VerticalOptions = LayoutOptions.Fill,
                Aspect = Aspect.AspectFill
            };
            parallaxView.Content = backgroundImage;
            
            // Create scrollable content
            var scrollView = new ScrollView
            {
                BackgroundColor = Colors.Transparent,
                Content = new StackLayout
                {
                    Padding = new Thickness(20),
                    Spacing = 15,
                    Children =
                    {
                        new Label 
                        { 
                            Text = "Article Title", 
                            FontSize = 32, 
                            FontAttributes = FontAttributes.Bold,
                            TextColor = Colors.White 
                        },
                        new Label 
                        { 
                            Text = "Lorem ipsum dolor sit amet...", 
                            FontSize = 16,
                            TextColor = Colors.White 
                        }
                        // Add more content
                    }
                }
            };
            
            // Bind ScrollView as Source
            parallaxView.Source = scrollView;
            
            // Add to page
            var grid = new Grid();
            grid.Children.Add(parallaxView);
            grid.Children.Add(scrollView);
            this.Content = grid;
        }
    }
}

ListView Integration

For data-driven scrollable content, use Syncfusion's SfListView with the parallax view.

Complete ListView Example

XAML:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:parallax="clr-namespace:Syncfusion.Maui.ParallaxView;assembly=Syncfusion.Maui.ParallaxView"
    xmlns:list="clr-namespace:Syncfusion.Maui.ListView;assembly=Syncfusion.Maui.ListView"
    x:Class="ParallaxViewDemo.MainPage">
    
    <Grid>
        <!-- Parallax View -->
        <parallax:SfParallaxView Source="{x:Reference listView}" x:Name="parallaxView">
            <parallax:SfParallaxView.Content>
                <Image Source="{Binding BackgroundImage}" 
                       BackgroundColor="Transparent"
                       HorizontalOptions="Fill" 
                       VerticalOptions="Fill" 
                       Aspect="AspectFill" />
            </parallax:SfParallaxView.Content>
        </parallax:SfParallaxView>
        
        <!-- ListView as Source -->
        <list:SfListView x:Name="listView" 
                         ItemsSource="{Binding Items}" 
                         BackgroundColor="Transparent"
                         ItemSize="100">
            <list:SfListView.ItemTemplate>
                <DataTemplate>
                    <ViewCell>
                        <Grid Padding="10" BackgroundColor="#80000000">
                            <Grid.ColumnDefinitions>
                                <ColumnDefinition Width="90" />
                                <ColumnDefinition Width="*" />
                            </Grid.ColumnDefinitions>
                            
                            <!-- Item Image -->
                            <Image Source="{Binding ItemImage}" 
                                   HeightRequest="80" 
                                   WidthRequest="80"
                                   Aspect="AspectFit"
                                   Grid.Column="0" 
                                   HorizontalOptions="Center"
                                   VerticalOptions="Center" />
                            
                            <!-- Item Details -->
                            <StackLayout Grid.Column="1" 
                                       VerticalOptions="Center" 
                                       Spacing="5">
                                <Label Text="{Binding Name}" 
                                       FontSize="18" 
                                       FontAttributes="Bold"
                                       TextColor="White" />
                                <Label Text="{Binding Author}" 
                                       FontSize="14" 
                                       TextColor="LightGray" />
                            </StackLayout>
                        </Grid>
                    </ViewCell>
                </DataTemplate>
            </list:SfListView.ItemTemplate>
        </list:SfListView>
    </Grid>
</ContentPage>

C# (ViewModel):

using System.Collections.ObjectModel;
using System.Reflection;

namespace ParallaxViewDemo
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            InitializeComponent();
            BindingContext = new ParallaxViewModel();
        }
    }
    
    public class ParallaxViewModel
    {
        public ImageSource BackgroundImage { get; set; }
        public ObservableCollection<MusicItem> Items { get; set; }
        
        public ParallaxViewModel()
        {
            Assembly assembly = typeof(ParallaxViewModel).GetTypeInfo().Assembly;
            
            // Load background image from resources
            BackgroundImage = ImageSource.FromResource(
                "ParallaxViewDemo.Resources.Images.music_background.jpg", 
                assembly);
            
            // Create sample data
            Items = new ObservableCollection<MusicItem>
            {
                new MusicItem 
                { 
                    Name = "Thriller", 
                    Author = "Michael Jackson",
                    ItemImage = ImageSource.FromResource(
                        "ParallaxViewDemo.Resources.Images.album1.png", assembly)
                },
                new MusicItem 
                { 
                    Name = "Like a Prayer", 
                    Author = "Madonna",
                    ItemImage = ImageSource.FromResource(
                        "ParallaxViewDemo.Resources.Images.album2.png", assembly)
                },
                new MusicItem 
                { 
                    Name = "When Doves Cry", 
                    Author = "Prince",
                    ItemImage = ImageSource.FromResource(
                        "ParallaxViewDemo.Resources.Images.album3.png", assembly)
                },
                new MusicItem 
                { 
                    Name = "I Wanna Dance", 
                    Author = "Whitney Houston",
                    ItemImage = ImageSource.FromResource(
                        "ParallaxViewDemo.Resources.Images.album4.png", assembly)
                },
                new MusicItem 
                { 
                    Name = "Rolling in the Deep", 
                    Author = "Adele",
                    ItemImage = ImageSource.FromResource(
                        "ParallaxViewDemo.Resources.Images.album5.png", assembly)
                },
                // Add more items...
            };
        }
    }
    
    public class MusicItem
    {
        public string Name { get; set; }
        public string Author { get; set; }
        public ImageSource ItemImage { get; set; }
    }
}

Programmatic ListView Binding

C# (Complete):

using Syncfusion.Maui.ParallaxView;
using Syncfusion.Maui.ListView;

namespace ParallaxViewDemo
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            InitializeComponent();
            
            var viewModel = new ParallaxViewModel();
            BindingContext = viewModel;
            
            // Create parallax view
            var parallaxView = new SfParallaxView();
            
            // Set background
            var backgroundImage = new Image
            {
                Source = viewModel.BackgroundImage,
                BackgroundColor = Colors.Transparent,
                HorizontalOptions = LayoutOptions.Fill,
                VerticalOptions = LayoutOptions.Fill,
                Aspect = Aspect.AspectFill
            };
            parallaxView.Content = backgroundImage;
            
            // Create ListView
            var listView = new SfListView
            {
                ItemsSource = viewModel.Items,
                BackgroundColor = Colors.Transparent,
                ItemSize = 100,
                ItemTemplate = new DataTemplate(() =>
                {
                    var grid = new Grid { Padding = 10 };
                    grid.ColumnDefinitions.Add(new ColumnDefinition { Width = 90 });
                    grid.ColumnDefinitions.Add(new ColumnDefinition { Width = GridLength.Star });
                    
                    var itemImage = new Image
                    {
                        HeightRequest = 80,
                        WidthRequest = 80,
                        Aspect = Aspect.AspectFit
                    };
                    itemImage.SetBinding(Image.SourceProperty, "ItemImage");
                    Grid.SetColumn(itemImage, 0);
                    
                    var stackLayout = new StackLayout 
                    { 
                        VerticalOptions = LayoutOptions.Center,
                        Spacing = 5 
                    };
                    
                    var nameLabel = new Label
                    {
                        FontSize = 18,
                        FontAttributes = FontAttributes.Bold,
                        TextColor = Colors.White
                    };
                    nameLabel.SetBinding(Label.TextProperty, "Name");
                    
                    var authorLabel = new Label
                    {
                        FontSize = 14,
                        TextColor = Colors.LightGray
                    };
                    authorLabel.SetBinding(Label.TextProperty, "Author");
                    
                    stackLayout.Children.Add(nameLabel);
                    stackLayout.Children.Add(authorLabel);
                    Grid.SetColumn(stackLayout, 1);
                    
                    grid.Children.Add(itemImage);
                    grid.Children.Add(stackLayout);
                    
                    return new ViewCell { View = grid };
                })
            };
            
            // Bind ListView as Source
            parallaxView.Source = listView;
            
            // Add to grid
            var mainGrid = new Grid();
            mainGrid.Children.Add(parallaxView);
            mainGrid.Children.Add(listView);
            
            this.Content = mainGrid;
        }
    }
}

Content Auto-Stretch Behavior

Important: The size of the Content view will automatically be stretched to match the size of the Source view. This means:

• You don't need to manually calculate or set Content dimensions
• The background will always cover the entire scrollable area
• The parallax effect works seamlessly across all scroll positions
• The Content maintains its aspect ratio while filling the available space

This auto-stretch behavior ensures that there are no gaps or visual glitches during scrolling, regardless of the Source content size.

GitHub Sample Links

For complete working examples, check out the official Syncfusion sample repository: MAUI Parallax View Sample Demos

Known Issues and Workarounds

Android Image Sizing Issue

Issue: In Android, when an image's pixel size cannot stretch to fit the Parallax View Source control during loading, it may result in a Java.Lang.RuntimeException.

GitHub Issue: dotnet/maui#11230

Workaround: Use images with appropriate resolution that can be scaled without quality loss. Ensure images are large enough to cover the expected scroll area without degradation.

Best Practices:

• Use high-resolution images for backgrounds (at least 2x the expected display size)
• Test on target Android devices to verify image loading
• Consider using vector graphics or scalable formats when possible
• Implement error handling for image loading failures

Next Steps

• [Customization](customization.md) - Learn how to adjust speed and orientation for different effects
• [Custom Controls](custom-controls.md) - Implement IParallaxView for custom scrollable controls

Troubleshooting

Issue: Parallax effect not visible

Cause: Source control has an opaque background Solution: Set BackgroundColor="Transparent" on the Source control (ScrollView or ListView)

Issue: Content doesn't cover entire scroll area

Cause: Content view is smaller than expected Solution: The Content should auto-stretch. Verify the Source has a defined size and the Content uses HorizontalOptions="Fill" and VerticalOptions="Fill"

Issue: Jerky or laggy scrolling

Cause: Complex Content or large images Solution: Optimize images, reduce Content complexity, or adjust the Speed property to reduce motion intensity