Quickstart: Animating your UI using library animations (XAML)

Animations in the Windows Runtime can enhance your app by adding movement and interactivity. By using the animations from the Windows Runtime animation library, you can integrate their look and feel into your app.

Note  To download a sample that demonstrates many of the concepts discussed in this topic, see the XAML personality animations sample.

 

Roadmap: How does this topic relate to others? See:

• Roadmap for Windows Runtime apps using C# or Visual Basic
• Roadmap for Windows Runtime apps using C++

Transition animations

Ideally, your app uses animations to enhance the user interface or to make it more attractive without annoying your users. One way you can do this is to apply animated transitions to UI so that when something enters or leaves the screen or otherwise changes, the animation draws the attention of the user to the change. For example, your buttons may rapidly fade in and out of view rather than just appear and disappear. We created a number of APIs that can be used to create recommended or typical animation transitions that are consistent. The example here shows how to apply an animation to a button so that it swiftly slides into view.

<Button Content="Transitioning Button">
     <Button.Transitions>
         <TransitionCollection> 
             <EntranceThemeTransition/>
         </TransitionCollection>
     </Button.Transitions>
 </Button> 

In this code, we add the EntranceThemeTransition object to the transition collection of the button. Now, when the button is first rendered, it swiftly slides into view rather than just appear. You can set a few properties on the animation object in order to adjust how far it slides and from what direction, but it's really meant to be a simple API for a specific scenario, that is, to make an eye-catching entrance.

You can also define transition animation themes in the style resources of your app, allowing you to apply the effect uniformly. This example is equivalent to the previous one, only it is applied using a Style:

<UserControl.Resources>
     <Style x:Key="DefaultButtonStyle" TargetType="Button">
         <Setter Property="Transitions">
             <Setter.Value>
                 <TransitionCollection>
                     <EntranceThemeTransition/>
                 </TransitionCollection>
             </Setter.Value>
        </Setter>
    </Style>
</UserControl.Resources>
      
<StackPanel x:Name="LayoutRoot">
    <Button Style="{StaticResource DefaultButtonStyle}" Content="Transitioning Button"/>
</StackPanel>

The previous examples apply a theme transition to an individual control, however, theme transitions are even more interesting when you apply them to a container of objects. When you do this, all the child objects of the container take part in the transition. In the following example, an EntranceThemeTransition is applied to a Grid of rectangles.

<!-- If you set an EntranceThemeTransition animation on a panel, the
     children of the panel will automatically offset when they animate
     into view to create a visually appealing entrance. -->        
<ItemsControl Grid.Row="1" x:Name="rectangleItems">
    <ItemsControl.ItemContainerTransitions>
        <TransitionCollection>
            <EntranceThemeTransition/>
        </TransitionCollection>
    </ItemsControl.ItemContainerTransitions>
    <ItemsControl.ItemsPanel>
        <ItemsPanelTemplate>
            <WrapGrid Height="400"/>
        </ItemsPanelTemplate>
    </ItemsControl.ItemsPanel>
            
    <!-- The sequence children appear depends on their order in 
         the panel's children, not necessarily on where they render
         on the screen. Be sure to arrange your child elements in
         the order you want them to transition into view. -->
    <ItemsControl.Items>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
    </ItemsControl.Items>
</ItemsControl>

The child rectangles of the Grid transition into view one after the other in a visually pleasing way rather than all at once as would be the case if you applied this animation to the rectangles individually.

Here's a video that demonstrates this animation:

Child objects of a container can also re-flow when one or more of those children change position. In the following example, we apply a RepositionThemeTransition to a grid of rectangles. When you remove one of the rectangles, all the other rectangles re-flow into their new position.

<Button Content="Remove Rectangle" Click="RemoveButton_Click"/>
        
<ItemsControl Grid.Row="1" x:Name="rectangleItems">
    <ItemsControl.ItemContainerTransitions>
        <TransitionCollection>
                    
            <!-- Without this, there would be no animation when items 
                 are removed. -->
            <RepositionThemeTransition/>
        </TransitionCollection>
    </ItemsControl.ItemContainerTransitions>
    <ItemsControl.ItemsPanel>
        <ItemsPanelTemplate>
            <WrapGrid Height="400"/>
        </ItemsPanelTemplate>
    </ItemsControl.ItemsPanel>
            
    <!-- All these rectangles are just to demonstrate how the items
         in the grid re-flow into position when one of the child items
         are removed. -->
    <ItemsControl.Items>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
        <Rectangle Fill="Red" Width="100" Height="100" Margin="10"/>
    </ItemsControl.Items>
</ItemsControl>

private void RemoveButton_Click(object sender, RoutedEventArgs e)
{
    if (rectangleItems.Items.Count > 0)
    {    
        rectangleItems.Items.RemoveAt(0);
    }                         
}

// .h
private:
void RemoveButton_Click(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e);

//.cpp
void BlankPage::RemoveButton_Click(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
    if (rectangleItems->Items->Size > 0)
    {    
        rectangleItems->Items->RemoveAt(0);
    }
}

This video demonstrates the animation that runs for the rectangles being removed:

You can apply multiple transition animations to a single object or object container. For example, if you want the list of rectangles to animate into view and also animate when they change position, you can apply the RepositionThemeTransition and EntranceThemeTransition like this:

...
<ItemsControl.ItemContainerTransitions>
    <TransitionCollection>
        <EntranceThemeTransition/>                    
        <RepositionThemeTransition/>
    </TransitionCollection>
</ItemsControl.ItemContainerTransitions>
...      

There are several transition effects to create animations on your UI elements as they are added, removed, reordered, and so on. The names of these APIs all contain "ThemeTransition":

API	Description
AddDeleteThemeTransition	Provides the animated transition behavior for when controls add or delete children or content. Typically the control is an item container.
ContentThemeTransition	Provides the animated transition behavior for when the content of a control is changing. You can apply this in addition to AddDeleteThemeTransition.
EdgeUIThemeTransition	Provides the animated transition behavior for a (small) edge UI transition.
EntranceThemeTransition	Provides the animated transition behavior for when controls first appear.
PaneThemeTransition	Provides the animated transition behavior for a panel (large edge UI) UI transition.
PopupThemeTransition	Provides the animated transition behavior that applies to pop-in components of controls (for example, tooltip-like UI on an object) as they appear.
ReorderThemeTransition	Provides the animated transition behavior for when list-view controls items change order. Typically this happens as a result of a drag-drop operation. Different controls and themes can have varying characteristics for the animations.
RepositionThemeTransition	Provides the animated transition behavior for when controls change position.

 

Theme animations

Transition animations are simple to apply. But you may want to have a bit more control over the timing and order of your animation effects. You can use theme animations to enable more control while still using a consistent theme for how your animation behaves. Theme animations also require less markup than custom animations. Here, we use the FadeOutThemeAnimation to make a rectangle fade out of view.

<StackPanel>    
    <StackPanel.Resources>
        <Storyboard x:Name="myStoryboard">
            <FadeOutThemeAnimation TargetName="myRectangle" />
        </Storyboard>
    </StackPanel.Resources>
    <Rectangle PointerPressed="Rectangle_Tapped" x:Name="myRectangle"  
              Fill="Blue" Width="200" Height="300"/>
</StackPanel>

// When the user taps the rectangle, the animation begins.
private void Rectangle_Tapped(object sender, PointerRoutedEventArgs e)
{
    myStoryboard.Begin();
}

' When the user taps the rectangle, the animation begins.
Private Sub Rectangle_Tapped(sender As Object, e As PointerRoutedEventArgs)
    myStoryboard.Begin()
End Sub

//.h
void Rectangle_Tapped(Platform::Object^ sender, Windows::UI::Xaml::Input::PointerRoutedEventArgs^ e);

//.cpp
void BlankPage::Rectangle_Tapped(Object^ sender, PointerRoutedEventArgs^ e)
{
    myStoryboard->Begin();
}

Unlike transition animations, a theme animation doesn't have a built-in trigger (the transition) that runs it automatically. You must use a Storyboard to contain a theme animation when you define it in XAML. You can also change the default behavior of the animation. For example, you can slow down the fade-out by increasing the Duration time value on the FadeOutThemeAnimation.

Note  For purposes of showing basic animation techniques, we're using app code to start the animation by calling methods of Storyboard. You can control how the Storyboard animations run using the Begin, Stop, Pause, and ResumeStoryboard methods. However, that's not typically how you include library animations in apps. Rather, you usually integrate the library animations into the XAML styles and templates applied to controls or elements. Learning about templates and visual states is a little more involved. But we do cover how you'd use library animations in visual states as part of the Storyboarded animations for visual states topic.

 

You can apply several other theme animations to your UI elements to create animation effects. The names of these API all contain "ThemeAnimation":

API	Description
DragItemThemeAnimation	Represents the preconfigured animation that applies to item elements being dragged.
DragOverThemeAnimation	Represents the preconfigured animation that applies to the elements underneath an element being dragged.
DropTargetItemThemeAnimation	The preconfigured animation that applies to potential drop target elements.
FadeInThemeAnimation	The preconfigured opacity animation that applies to controls when they first appear.
FadeOutThemeAnimation	The preconfigured opacity animation that applies to controls when they are removed from UI or hidden.
PointerDownThemeAnimation	The preconfigured animation for user action that taps or clicks an item or element.
PointerUpThemeAnimation	The preconfigured animation for user action that runs after a user taps down on an item or element and the action is released.
PopInThemeAnimation	The preconfigured animation that applies to pop-in components of controls as they appear. This animation combines opacity and translation.
PopOutThemeAnimation	The preconfigured animation that applies to pop-in components of controls as they are closed or removed. This animation combines opacity and translation.
RepositionThemeAnimation	The preconfigured animation for an object as it is repositioned.
SplitCloseThemeAnimation	The preconfigured animation that conceals a target UI using a split animation.
SplitOpenThemeAnimation	The preconfigured animation that reveals a target UI using a split animation.
SwipeBackThemeAnimation	The preconfigured animation that applies to controls when an element slides back into its layout slot after a swipe interaction.
SwipeHintThemeAnimation	The preconfigured animation that indicates that a swipe gesture is now possible.

 

Built-in animations for controls

There are animations built into some of the Windows Runtime controls, as part of their control logic and default XAML templates. We recommend that you get to know these controls so that you can use them for your animations in UI.

Here is a list of some controls with built-in animations:

• AppBar, CommandBar: FadeInThemeAnimation and FadeOutThemeAnimation
• ListView, GridView, GroupItem: AddDeleteThemeTransition, ReorderThemeTransition, ContentThemeTransition, EntranceThemeTransition
• ListViewItem, GridViewItem: PointerDownThemeAnimation, SwipeHintThemeAnimation, FadeInThemeAnimation and FadeOutThemeAnimation (for multi-drag hinting), DragItemThemeAnimation, DropTargetItemThemeAnimation
• ToolTip: FadeInThemeAnimation and FadeOutThemeAnimation

Note  This isn't the complete list. For more info see the "Animating ..." topics in this same area, or the "styles and templates" topics for specific controls.

 

Create your own animations

When theme animations are not enough for your needs, you can create your own animations. You animate objects by animating one or more of their property values. For example, you can animate the width of a rectangle, the angle of a RotateTransform, or the color value of a button. We term this type of custom animation a storyboarded animation, to distinguish it from the library animations that the Windows Runtime already provides as a preconfigured animation type. For storyboarded animations, you use an animation that can change values of a particular type (for example DoubleAnimation to animate a Double) and put that animation within a Storyboard to control it.

In order to be animated, the property you are animating must be a dependency property. For more info about dependency properties, see Dependency properties overview. For more info on creating custom storyboarded animations, including how to target and control them, see Storyboarded animations.

The biggest area of app UI definition in XAML where you'll define custom storyboarded animations is if you are defining visual states for controls in XAML. You'll be doing this either because you are creating a new control class, or because you are re-templating an existing control that has visual states in its control template. For more info, see Storyboarded animations for visual states. These animations aren't usually transitions over time at all, they happen instantaneously, and are really more of a technique for defining a set of property changes for a state. They don't necessarily apply a visually animated behavior to a UI, although as you'll see the visual states for controls often include the library animations themselves. In this case the theme animations do apply a change over time, though it's usually a short duration.

Related topics

Roadmap for creating apps using C# or VB

Property-path syntax

Dependency properties overview

Storyboarded animations

Storyboarded animations for visual states

Key-frame animations and easing function animations

Storyboard

Storyboard.TargetProperty