Carousel Page

Navigating between pages using a swipe gesture

PDF for offline use
Sample Code:
Related Articles:
Related APIs:

Let us know how you feel about this

Translation Quality


0/250

The Xamarin.Forms CarouselPage is a page that users can swipe from side to side to navigate through pages of content, like a gallery. This article demonstrates how to use a CarouselPage to navigate through a collection of pages.

Overview

The following screenshots show a CarouselPage on each platform:

The layout of a CarouselPage is identical on each platform. Pages can be navigated through by swiping right to left to navigate forwards through the collection, and by swiping left to right to navigate backwards through the collection. The following screenshots show the first page in a CarouselPage instance:

Swiping from right to left moves to the second page, as shown in the following screenshots:

Swiping from right to left again moves to the third page, while swiping from left to right returns to the previous page.

Creating a CarouselPage

Two approaches can be used to create a CarouselPage:

With both approaches, the CarouselPage will then display each page in turn, with a swipe interaction moving to the next page to be displayed. This navigation experience will feel natural and familiar to Windows Phone users.

A CarouselPage can only be populated with ContentPage instances, or ContentPage derivatives.

Populating a CarouselPage with a Page Collection

The following XAML code example shows a CarouselPage that displays three ContentPage instances:

<CarouselPage xmlns="http://xamarin.com/schemas/2014/forms"
              xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
              x:Class="CarouselPageNavigation.MainPage">
    <ContentPage>
        <ContentPage.Padding>
            <OnPlatform x:TypeArguments="Thickness" iOS="0,40,0,0" Android="0,40,0,0" />
        </ContentPage.Padding>
        <StackLayout>
            <Label Text="Red" FontSize="Medium" HorizontalOptions="Center" />
            <BoxView Color="Red" WidthRequest="200" HeightRequest="200" HorizontalOptions="Center" VerticalOptions="CenterAndExpand" />
        </StackLayout>
    </ContentPage>
    <ContentPage>
        ...
    </ContentPage>
    <ContentPage>
        ...
    </ContentPage>
</CarouselPage>

The following code example shows the equivalent UI in C#:

public class MainPageCS : CarouselPage
{
    public MainPageCS ()
    {
        var padding = new Thickness (0, Device.OnPlatform (40, 40, 0), 0, 0);
        var redContentPage = new ContentPage {
            Padding = padding,
            Content = new StackLayout {
                Children = {
                    new Label {
                        Text = "Red",
                        FontSize = Device.GetNamedSize (NamedSize.Medium, typeof(Label)),
                        HorizontalOptions = LayoutOptions.Center
                    },
                    new BoxView {
                        Color = Color.Red,
                        WidthRequest = 200,
                        HeightRequest = 200,
                        HorizontalOptions = LayoutOptions.Center,
                        VerticalOptions = LayoutOptions.CenterAndExpand
                    }
                }
            }
        };
        var greenContentPage = new ContentPage {
            Padding = padding,
            Content = new StackLayout {
                ...
            }
        };
        var blueContentPage = new ContentPage {
            Padding = padding,
            Content = new StackLayout {
                ...
            }
        };

        Children.Add (redContentPage);
        Children.Add (greenContentPage);
        Children.Add (blueContentPage);
    }
}

Each ContentPage simply displays a Label for a particular color and a BoxView of that color.

The CarouselPage does not support UI virtualization. Therefore, performance may be affected if the CarouselPage contains too many child elements.

If a CarouselPage is embedded into the Detail page of a MasterDetailPage, the MasterDetailPage.IsGestureEnabled property should be set to false to prevent gesture conflicts between the CarouselPage and the MasterDetailPage.

For more information about the CarouselPage, see Chapter 25 of Charles Petzold's Xamarin.Forms book.

Populating a CarouselPage with a Template

The following XAML code example shows a CarouselPage constructed by assigning a DataTemplate to the ItemTemplate property to return pages for objects in the collection:

<CarouselPage xmlns="http://xamarin.com/schemas/2014/forms"
              xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
              x:Class="CarouselPageNavigation.MainPage">
    <CarouselPage.ItemTemplate>
        <DataTemplate>
            <ContentPage>
                <ContentPage.Padding>
                    <OnPlatform x:TypeArguments="Thickness" iOS="0,40,0,0" Android="0,40,0,0" />
                </ContentPage.Padding>
                <StackLayout>
                    <Label Text="{Binding Name}" FontSize="Medium" HorizontalOptions="Center" />
                    <BoxView Color="{Binding Color}" WidthRequest="200" HeightRequest="200" HorizontalOptions="Center" VerticalOptions="CenterAndExpand" />
                </StackLayout>
            </ContentPage>
        </DataTemplate>
    </CarouselPage.ItemTemplate>
</CarouselPage>

The CarouselPage is populated with data by setting the ItemsSource property in the constructor for the code-behind file:

public MainPage ()
{
    ...
    ItemsSource = ColorsDataModel.All;
}

The following code example shows the equivalent CarouselPage created in C#:

public class MainPageCS : CarouselPage
{
    public MainPageCS ()
    {
        ItemTemplate = new DataTemplate (() => {
            var nameLabel = new Label {
                FontSize = Device.GetNamedSize (NamedSize.Medium, typeof(Label)),
                HorizontalOptions = LayoutOptions.Center
            };
            nameLabel.SetBinding (Label.TextProperty, "Name");

            var colorBoxView = new BoxView {
                WidthRequest = 200,
                HeightRequest = 200,
                HorizontalOptions = LayoutOptions.Center,
                VerticalOptions = LayoutOptions.CenterAndExpand
            };
            colorBoxView.SetBinding (BoxView.ColorProperty, "Color");

            return new ContentPage {
                Padding = new Thickness (0, Device.OnPlatform (40, 40, 0), 0, 0),
                Content = new StackLayout {
                    Children = {
                        nameLabel,
                        colorBoxView
                    }
                }
            };
        });

        ItemsSource = ColorsDataModel.All;
    }
}

Each ContentPage simply displays a Label for a particular color and a BoxView of that color.

The CarouselPage does not support UI virtualization. Therefore, performance may be affected if the CarouselPage contains too many child elements.

If a CarouselPage is embedded into the Detail page of a MasterDetailPage, the MasterDetailPage.IsGestureEnabled property should be set to false to prevent gesture conflicts between the CarouselPage and the MasterDetailPage.

For more information about the CarouselPage, see Chapter 25 of Charles Petzold's Xamarin.Forms book.

Summary

This article demonstrated how to use a CarouselPage to navigate through a collection of pages. The CarouselPage is a page that users can swipe from side to side to navigate through pages of content, like a gallery, and provides a navigation experience that feels natural and familiar to Windows Phone users.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.