Xamarin Community Toolkit StateLayout
Displaying a specific view when your app is in a specific state is a common pattern throughout any mobile app. Examples range from creating loading views to overlay on the screen, or on a subsection of the screen. Empty state views can be created for when there's no data to display, and error state views can be displayed when an error occurs.
Getting started
The StateLayout control enables the user to turn any layout element like a Grid
or StackLayout
into an individual state-aware element. Each layout that you make state-aware, using the StateLayout attached properties, contains a collection of StateView
objects. These objects can be used as templates for the different states supported by StateLayout. Whenever the CurrentState
property is set to a value that matches the State
property of one of the StateViews its contents will be displayed instead of the main content.
LayoutState enumeration
The LayoutState
enumeration supports one of the following values:
None
(default, this will show the initial view)Loading
Saving
Success
Error
Empty
Custom
Syntax
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:xct="http://xamarin.com/schemas/2020/toolkit"
x:Class="MyLittleApp.MainPage">
<Grid xct:StateLayout.CurrentState="{Binding CurrentState}">
<xct:StateLayout.StateViews>
<xct:StateView StateKey="Loading">
<Grid BackgroundColor="White">
<StackLayout VerticalOptions="Center" HorizontalOptions="Center">
<ActivityIndicator Color="#1abc9c" />
<Label Text="Loading..." HorizontalOptions="Center" />
</StackLayout>
</Grid>
</xct:StateView>
</xct:StateLayout.StateViews>
...
</Grid>
</ContentPage>
Use custom states
Besides the built-in states StateLayout also supports a Custom
state. By setting State
to Custom
and adding a CustomStateKey
you can create custom states beyond the built-in states. You can use the CurrentCustomStateKey
on your root StateLayout element to bind a variable that indicates when to show one of your custom states.
Syntax
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:xct="clr-namespace:Xamarin.CommunityToolkit.Views;assembly=Xamarin.CommunityToolkit"
x:Class="MyLittleApp.MainPage">
<StackLayout Padding="10" xct:StateLayout.CurrentState="{Binding CurrentState}" xct:StateLayout.CurrentCustomStateKey="{Binding CustomState}">
<xct:StateLayout.StateViews>
<xct:StateView StateKey="Custom" CustomStateKey="ThisIsACustomState">
<Label Text="Hi, I'm a custom state!" />
</xct:StateView>
<xct:StateView StateKey="Custom" CustomStateKey="ThisIsACustomStateToo">
<Label Text="Hi, I'm a custom state too!" />
</xct:StateView>
</xct:StateLayout.StateViews>
<Label Text="This is the normal state." />
</StackLayout>
</ContentPage>
Use repeating states
When loading multiple items of the same type it could be beneficial to repeat a piece of XAML without having to copy paste it multiple times. This is where the RepeatCount
property should be used. By defining a Template
it's possible to repeat the same piece of XAML while only defining it once.
Note
When using a RepeatCount
that is greater than 1 you have to use the Template
property to provide your content. Providing Content
to a StateView
while providing a RepeatCount
greater than 1 will result in an exception.
Syntax
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:xct="clr-namespace:Xamarin.CommunityToolkit.Views;assembly=Xamarin.CommunityToolkit"
x:Class="MyLittleApp.MainPage">
<StackLayout xct:StateLayout.CurrentState="{Binding CurrentState}">
<xct:StateLayout.StateViews>
<xct:StateView StateKey="Loading" RepeatCount="3">
<xct:StateView.Template>
<DataTemplate>
<StackLayout Spacing="8">
<BoxView CornerRadius="8" HeightRequest="40" BackgroundColor="#CCCCCC" WidthRequest="120" />
<BoxView CornerRadius="8" HeightRequest="40" BackgroundColor="#CCCCCC" WidthRequest="200" />
</StackLayout>
</DataTemplate>
</xct:StateView.Template>
</xct:StateView>
</xct:StateLayout.StateViews>
...
<StackLayout>
</ContentPage>
Properties
The following properties are available on the StateLayout
object:
Property | Type | Description |
---|---|---|
CurrentState | LayoutState |
Defines the current state of the layout and which template to show. |
CurrentCustomStateKey | string | Pair this with State="Custom" on a StateView to add custom states. |
StateViews | IList<StateView> |
A list of StateView objects that contains a template per State. |
The following properties are available on the StateView
object:
Property | Type | Description |
---|---|---|
CustomStateKey | string | Defines the current state of the layout and which template to show. |
RepeatCount | int | The amount of times the Template should be repeated. |
Template | DataTemplate |
Defines a template to show for this state. |
State | LayoutState |
Defines the current state of the layout and which template to show. |
Sample
StateLayout sample page Source
You can see this in action in the Xamarin Community Toolkit Sample App.