Animating XAML elements with composition animations

This article introduces properties that let you animate a XAML UIElement with the performance of composition animations and the ease of setting XAML properties.

Typically, you use either XAML or Composition APIs to build animations in your Windows apps:

• Use XAML constructs like Storyboarded animations, or the *ThemeTransition and *ThemeAnimation classes in the Microsoft.UI.Xaml.Media.Animation namespace.
• Use composition animations as described in Using the Visual Layer with XAML.

Using the visual layer provides better performance than using the XAML constructs. But using ElementCompositionPreview to get the element's underlying composition Visual object, and then animating the Visual with composition animations, is more complex to use.

However, some properties on a UIElement let you animate them directly using composition animations without the requirement to get the underlying composition Visual.

The WinUI 3 Gallery app includes interactive examples of most WinUI 3 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub

Composition rendering properties replace XAML rendering properties

This table shows the properties you can use to modify the rendering of a UIElement, that can also be animated with a CompositionAnimation.

The TransformMatrix property value is combined with the Scale, Rotation, and Translation properties in the following order: TransformMatrix, Scale, Rotation, Translation.

These properties don't affect the element's layout, so modifying these properties does not cause a new Measure/Arrange pass.

These properties have the same purpose and behavior as the like-named properties on the composition Visual class (except for Translation, which isn't on Visual).

Example: Setting the Scale property

This example shows how to set the Scale property on a Button.

<Button Scale="2,2,1" Content="I am a large button" />

var button = new Button();
button.Content = "I am a large button";
button.Scale = new Vector3(2.0f,2.0f,1.0f);

Mutual exclusivity between composition and XAML rendering properties

The properties that can be animated with a CompositionAnimation are replacements for several existing UIElement properties:

• RenderTransform
• RenderTransformOrigin
• Projection
• Transform3D

When you set (or animate) any of the new properties, you cannot use the old properties. Conversely, if you set (or animate) any of the old properties, you cannot use the new properties.

You also cannot use the new properties if you use ElementCompositionPreview to get and manage the Visual yourself using these methods:

• ElementCompositionPreview.GetElementVisual
• ElementCompositionPreview.SetIsTranslationEnabled

It's possible to switch from one set of properties by clearing them, though for simplicity it's not recommended. If the property is backed by a DependencyProperty (for example, UIElement.Projection is backed by UIElement.ProjectionProperty), then call ClearValue to restore it to its "unused" state. Otherwise (for example, the Scale property), set the property to its default value.

Animating UIElement properties with CompositionAnimation

You can animate the rendering properties listed in the table with a CompositionAnimation. These properties can also be referenced by an ExpressionAnimation.

Use the StartAnimation and StopAnimation methods on UIElement to animate the UIElement properties.

Example: Animating the Scale property with a Vector3KeyFrameAnimation

This example shows how to animate the scale of a Button.

var compositor = Window.Current.Compositor;
var animation = compositor.CreateVector3KeyFrameAnimation();

animation.InsertKeyFrame(1.0f, new Vector3(2.0f,2.0f,1.0f));
animation.Duration = TimeSpan.FromSeconds(1);
animation.Target = "Scale";

button.StartAnimation(animation);

Example: Animating the Scale property with an ExpressionAnimation

A page has two buttons. The second button animates to be twice as large (via scale) as the first button.

<Button x:Name="sourceButton" Content="Source"/>
<Button x:Name="destinationButton" Content="Destination"/>

Compositor compositor =
        CompositionTarget.GetCompositorForCurrentThread();
ExpressionAnimation animation = 
        compositor.CreateExpressionAnimation("sourceButton.Scale*2");
animation.SetExpressionReferenceParameter("sourceButton", sourceButton);
animation.Target = "Scale";
destinationButton.StartAnimation(animation);

UWP and WinUI 2

To get the Compositor in a UWP app, use the Window.Compositor property:

Compositor compositor = Window.Current.Compositor;

Related topics

• Storyboarded animations
• Using the Visual Layer with XAML
• Transforms overview