Class SfCarousel

The SfCarousel class represents a control that allows user navigate through a collection of galleried items.

Inheritance

System.Object

SfCarousel

Implements

ICarousel

Microsoft.Maui.IView

Microsoft.Maui.IElement

Microsoft.Maui.ITransform

Namespace: Syncfusion.Maui.Toolkit.Carousel

Assembly: Syncfusion.Maui.Toolkit.dll

Syntax

public class SfCarousel : View, ICarousel, IView, IElement, ITransform

Examples

The below example shows how to initialize the SfCarousel with model and view model.

public class ImageModel
{
    public string Image { get; set; }
    public ImageModel(string image)
    {
        Image = image;
    }
}

public class GalleryViewModel
{
    private ObservableCollection<ImageModel> imageCollection;
    public ObservableCollection<ImageModel> ImageCollection { get; set; }
    public GalleryViewModel()
    {
        ImageCollection = new ObservableCollection<ImageModel>()
        {
            new ImageModel("image1.png"),
            new ImageModel("image2.png"),
            new ImageModel("image3.png"),
        };
    }
}

XAML
C#

<ContentPage.BindingContext>
    <local:GalleryViewModel x:Name="galleryViewModel" />
</ContentPage.BindingContext>
<ContentPage.Resources>
    <ResourceDictionary>
        <DataTemplate x:Key="itemTemplate">
            <Grid>
               <Image x:Name="image" Source="{Binding Image}" />
            </Grid>
        </DataTemplate>
    </ResourceDictionary>
</ContentPage.Resources>
<ContentPage.Content>
    <carousel:SfCarousel
        x:Name="carousel"
        ItemTemplate="{x:StaticResource itemTemplate}"
        ItemsSource="{Binding ImageCollection}" />
</ContentPage.Content>

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
        GalleryViewModel galleryViewModel = new GalleryViewModel();
        this.BindingContext = galleryViewModel;
        var itemTemplate = new DataTemplate(() =>
        {
            var grid = new Grid();
            var image = new Image();
            image.SetBinding(Image.SourceProperty, "Image");
            grid.Children.Add(image);
            return grid;
        });
        SfCarousel carousel = new SfCarousel();
        carousel.ItemTemplate = itemTemplate;
        carousel.SetBinding(SfCarousel.ItemsSourceProperty, "ImageCollection");
        this.Content = carousel;
    }
}

Constructors

SfCarousel()

Initializes a new instance of the SfCarousel class.

Declaration

public SfCarousel()

Fields

AllowLoadMoreProperty

Identifies the AllowLoadMore bindable property.

Declaration

public static readonly BindableProperty AllowLoadMoreProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for AllowLoadMore bindable property.

DurationProperty

Identifies the Duration bindable property.

Declaration

public static readonly BindableProperty DurationProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for Duration bindable property.

EnableInteractionProperty

Identifies the EnableInteraction bindable property.

Declaration

public static readonly BindableProperty EnableInteractionProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for EnableInteraction bindable property.

EnableVirtualizationProperty

Identifies the EnableVirtualization bindable property.

Declaration

public static readonly BindableProperty EnableVirtualizationProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for EnableVirtualization bindable property.

ItemHeightProperty

Identifies the ItemHeight bindable property.

Declaration

public static readonly BindableProperty ItemHeightProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for ItemHeight bindable property.

ItemSpacingProperty

Identifies the ItemSpacing bindable property.

Declaration

public static readonly BindableProperty ItemSpacingProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for ItemSpacing bindable property.

ItemsSourceProperty

Identifies the ItemsSource bindable property.

Declaration

public static readonly BindableProperty ItemsSourceProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for ItemsSource bindable property.

ItemTemplateProperty

Identifies the ItemTemplate bindable property.

Declaration

public static readonly BindableProperty ItemTemplateProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for ItemTemplate bindable property.

ItemWidthProperty

Identifies the ItemWidth bindable property.

Declaration

public static readonly BindableProperty ItemWidthProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for ItemWidth bindable property.

LoadMoreItemsCountProperty

Identifies the LoadMoreItemsCount bindable property.

Declaration

public static readonly BindableProperty LoadMoreItemsCountProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for LoadMoreItemsCount bindable property.

LoadMoreViewProperty

Identifies the LoadMoreView bindable property.

Declaration

public static readonly BindableProperty LoadMoreViewProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for LoadMoreView bindable property.

OffsetProperty

Identifies the Offset bindable property.

Declaration

public static readonly BindableProperty OffsetProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for Offset bindable property.

RotationAngleProperty

Identifies the RotationAngle bindable property.

Declaration

public static readonly BindableProperty RotationAngleProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for RotationAngle bindable property.

ScaleOffsetProperty

Identifies the ScaleOffset bindable property.

Declaration

public static readonly BindableProperty ScaleOffsetProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for ScaleOffset bindable property.

SelectedIndexProperty

Identifies the SelectedIndex bindable property.

Declaration

public static readonly BindableProperty SelectedIndexProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for SelectedIndex bindable property.

SelectedItemOffsetProperty

Identifies the SelectedItemOffset bindable property.

Declaration

public static readonly BindableProperty SelectedItemOffsetProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for SelectedItemOffset bindable property.

SwipeMovementModeProperty

Identifies the SwipeMovementMode bindable property.

Declaration

public static readonly BindableProperty SwipeMovementModeProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for SwipeMovementMode bindable property.

ViewModeProperty

Identifies the ViewMode bindable property.

Declaration

public static readonly BindableProperty ViewModeProperty

Field Value

Type	Description
Microsoft.Maui.Controls.BindableProperty	The identifier for ViewMode bindable property.

Properties

AllowLoadMore

Gets or sets a value indicating whether the carousel control is configured to load additional items dynamically.

Declaration

public bool AllowLoadMore { get; set; }

Property Value

Type	Description
System.Boolean	`true` if additional items can be loaded dynamically; otherwise, `false`.

Examples

Below is an example of how to configure the AllowLoadMore property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    AllowLoadMore="True" />

SfCarousel carousel = new SfCarousel();
carousel.AllowLoadMore = true;
this.Content = carousel;

Duration

Gets or sets the duration for the selection animation in the carousel, allowing you to adjust the delay of the effect.

Declaration

public int Duration { get; set; }

Property Value

Type	Description
System.Int32	The default value is 600 milliseconds.

Examples

Below is an example of how to configure the Duration property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    Duration="300" />

SfCarousel carousel = new SfCarousel();
carousel.Duration = 300;
this.Content = carousel;

EnableInteraction

Gets or sets a value indicating whether user interaction with the carousel is enabled or disabled.

Declaration

public bool EnableInteraction { get; set; }

Property Value

Type	Description
System.Boolean	`true` if interaction is enabled; otherwise, `false`.

Examples

Below is an example of how to configure the EnableInteraction property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    EnableInteraction="false" />

SfCarousel carousel = new SfCarousel();
carousel.EnableInteraction = false;
this.Content = carousel;

EnableVirtualization

Gets or sets a value indicating whether the virtualization is enabled or not.

Declaration

public bool EnableVirtualization { get; set; }

Property Value

Type	Description
System.Boolean	`true` if virtualization is enabled; otherwise, `false`.

Remarks

This property is effective only when the carousel's view mode is set to Linear.

Examples

Below is an example of how to set the EnableVirtualization property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    EnableVirtualization="True" />

SfCarousel carousel = new SfCarousel();
carousel.EnableVirtualization = true;
this.Content = carousel;

ItemHeight

Gets or sets the height of each item in the carousel, allowing customization to suit design specifications.

Declaration

public int ItemHeight { get; set; }

Property Value

Type	Description
System.Int32	The default value is 350 for desktop platforms and 300 for mobile devices.

Examples

Below is an example of how to configure the ItemHeight property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    ItemHeight="150" />

SfCarousel carousel = new SfCarousel();
carousel.ItemHeight = 150;
this.Content = carousel;

ItemSpacing

Gets or sets the spacing value between items in the carousel. This property adjusts the space separating each item.

Declaration

public int ItemSpacing { get; set; }

Property Value

Type	Description
System.Int32	The default value is 12.

Remarks

This property is effective only when the view mode is set to linear.

Examples

Below is an example of how to configure the ItemSpacing property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    ItemSpacing="10" />

SfCarousel carousel = new SfCarousel();
carousel.ItemSpacing = 10;
this.Content = carousel;

ItemsSource

Gets or sets the collection of items to be displayed in the carousel, allowing each item to have a different view based on the template.

Declaration

public IEnumerable<object> ItemsSource { get; set; }

Property Value

Type	Description
System.Collections.Generic.IEnumerable<System.Object>	The default value is null, indicating no items are initially set.

Examples

Below is an example of how to configure the ItemsSource property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    ItemsSource="{Binding ImageCollection}" />

SfCarousel carousel = new SfCarousel();
carousel.SetBinding(SfCarousel.ItemsSourceProperty, "ImageCollection");
this.Content = carousel;

ItemTemplate

Gets or sets the data template that defines the visual representation of each item in the carousel.

Declaration

public DataTemplate ItemTemplate { get; set; }

Property Value

Type	Description
Microsoft.Maui.Controls.DataTemplate	The default value is null, indicating no template is set initially.

Examples

Below is an example of how to configure the ItemTemplate property using XAML and C#:

XAML
C#

<carousel:SfCarousel
	x:Name="carousel">
	<carousel:SfCarousel.ItemTemplate>
		<DataTemplate>
			<Image Aspect = "Fill"
					HeightRequest="100"
					Source="{Binding ImageName}"
					WidthRequest="100" />
		</DataTemplate>
	</carousel:SfCarousel.ItemTemplate>
</carousel:SfCarousel>

var itemTemplate = new DataTemplate(() =>
{
	var grid = new Grid();
	var nameLabel = new Image();
	nameLabel.SetBinding(Image.SourceProperty, "ImageName");
	grid.Children.Add(nameLabel);
	return grid;
});
SfCarousel carousel = new SfCarousel();
carousel.ItemTemplate = itemTemplate;
this.Content = carousel;

ItemWidth

Gets or sets the width of each item in the carousel, allowing customization to suit design specifications.

Declaration

public int ItemWidth { get; set; }

Property Value

Type	Description
System.Int32	The default value is 250 for desktop platforms and 200 for mobile devices.

Examples

Below is an example of how to configure the ItemWidth property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    ItemWidth="150" />

SfCarousel carousel = new SfCarousel();
carousel.ItemWidth = 150;
this.Content = carousel;

LoadMoreItemsCount

Gets or sets the number of additional items to load when the load more functionality is triggered in the carousel.

Declaration

public int LoadMoreItemsCount { get; set; }

Property Value

Type	Description
System.Int32	The default value is 3.

Examples

Below is an example of how to configure the LoadMoreItemsCount property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    AllowLoadMore="True"
    LoadMoreItemsCount="2" />

SfCarousel carousel = new SfCarousel();
carousel.AllowLoadMore = true;
LoadMoreItemsCount = 2;
this.Content = carousel;

LoadMoreView

Gets or sets the custom view displayed when additional items are loaded in the carousel, replacing the default "Load More" label.

Declaration

public View LoadMoreView { get; set; }

Property Value

Type	Description
Microsoft.Maui.Controls.View	The default value is null, indicating no custom view is set initially.

Examples

Below is an example of how to configure the LoadMoreView property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    AllowLoadMore="True"
    LoadMoreItemsCount="2">
    <carousel:SfCarousel.LoadMoreView>
        <Border Stroke="LightGray" StrokeThickness="1" StrokeShape="RoundRectangle 8">
            <Label
                HorizontalTextAlignment="Center"
                Text="Load More View"
                VerticalTextAlignment="Center" />
        </Border>
    </carousel:SfCarousel.LoadMoreView>
</carousel:SfCarousel>

SfCarousel carousel = new SfCarousel();
carousel.AllowLoadMore = true;
carousel.LoadMoreItemsCount = 2;
carousel.LoadMoreView = new Border()
{
    Content = new Label() { Text = "Load More View", HorizontalTextAlignment = TextAlignment.Center, VerticalTextAlignment = TextAlignment.Center },
    Stroke = Colors.LightGray,
    StrokeThickness = 1,
    StrokeShape = new Microsoft.Maui.Controls.Shapes.RoundRectangle() { CornerRadius = 8 },
};
this.Content = carousel;

Offset

Gets or sets the spacing between each item in the carousel when the view mode is set to default, allowing for visual separation.

Declaration

public float Offset { get; set; }

Property Value

Type	Description
System.Single	The default value is 40f for desktop and 18f for mobile devices.

Remarks

This property is effective only in the default view mode.

Examples

Below is an example of how to configure the Offset property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    Offset="10" />

SfCarousel carousel = new SfCarousel();
carousel.Offset = 10;
this.Content = carousel;

RotationAngle

Gets or sets the angle at which unselected items are tilted in the carousel.

Declaration

public int RotationAngle { get; set; }

Property Value

Type	Description
System.Int32	The default value is 45 degrees.

Remarks

This property is effective only when the view mode is set to the default mode.

Examples

Below is an example of how to configure the RotationAngle property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    RotationAngle="30" />

SfCarousel carousel = new SfCarousel();
carousel.RotationAngle = 30;
this.Content = carousel;

ScaleOffset

Gets or sets the scaling ratio that differentiates unselected items in the carousel when the view mode is set to default.

Declaration

public float ScaleOffset { get; set; }

Property Value

Type	Description
System.Single	The default value is 0.8f for desktop and 0.7f for mobile devices.

Remarks

This property is effective only in the default view mode.

Examples

Below is an example of how to configure the ScaleOffset property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    ScaleOffset="0.7" />

SfCarousel carousel = new SfCarousel();
carousel.ScaleOffset = 0.7;
this.Content = carousel;

SelectedIndex

Gets or sets the index of the item that is currently selected and centered in the carousel control.

Declaration

public int SelectedIndex { get; set; }

Property Value

Type	Description
System.Int32	The default value is 0, indicating the first item.

Examples

Below is an example of how to set the SelectedIndex property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    SelectedIndex="2" />

SfCarousel carousel = new SfCarousel();
carousel.SelectedIndex = 2;
this.Content = carousel;

SelectedItemOffset

Gets or sets the space between the selected item and unselected items in the carousel when the view mode is set to default.

Declaration

public int SelectedItemOffset { get; set; }

Property Value

Type	Description
System.Int32	The default value is 20 for Windows and 40 for other platforms.

Remarks

This property is effective only in the default view mode.

Examples

Below is an example of how to configure the SelectedItemOffset property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    SelectedItemOffset="30" />

SfCarousel carousel = new SfCarousel();
carousel.SelectedItemOffset = 30;
this.Content = carousel;

SwipeMovementMode

Gets or sets the scroll mode for the carousel, determining whether items are scrolled individually or in groups.

Declaration

public SwipeMovementMode SwipeMovementMode { get; set; }

Property Value

Type
SwipeMovementMode

Examples

Below is an example of how to configure the SwipeMovementMode property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    SwipeMovementMode="MultipleItems" />

SfCarousel carousel = new SfCarousel();
carousel.SwipeMovementMode = SwipeMovementMode.MultipleItems;
this.Content = carousel;

ViewMode

Gets or sets the mode that determines whether the carousel items are arranged in a default 3D layout or a linear horizontal layout.

Declaration

public ViewMode ViewMode { get; set; }

Property Value

Type	Description
ViewMode	The default value is "Default", indicating the 3D view mode..

Examples

Below is an example of how to configure the ViewMode property using XAML and C#:

XAML
C#

<carousel:SfCarousel
    x:Name="carousel"
    ViewMode="Linear" />

SfCarousel carousel = new SfCarousel();
carousel.ViewMode = ViewMode.Linear;
this.Content = carousel;

Methods

LoadMore()

Triggers the loading of additional items into the carousel.

Declaration

public void LoadMore()

MoveNext()

Advances the carousel selection from right to left, incrementing the selected index by one.

Declaration

public void MoveNext()

MovePrevious()

Moves the carousel selection from left to right, decrementing the selected index by one.

Declaration

public void MovePrevious()

Events

SelectionChanged

Triggered when an item is selected from the list of unselected items in the SfCarousel.

Declaration

public event EventHandler<SelectionChangedEventArgs> SelectionChanged

Event Type

Type
System.EventHandler<SelectionChangedEventArgs>

SwipeEnded

Triggered when a swipe gesture is completed in the SfCarousel.

Declaration

public event EventHandler<EventArgs> SwipeEnded

Event Type

Type
System.EventHandler<System.EventArgs>

SwipeStarted

Triggered when a swipe gesture initiates an item selection in the SfCarousel.

Declaration

public event EventHandler<SwipeStartedEventArgs> SwipeStarted

Event Type

Type
System.EventHandler<SwipeStartedEventArgs>

Implements

ICarousel

Microsoft.Maui.IView

Microsoft.Maui.IElement

Microsoft.Maui.ITransform