Skip to main content

Using keyframe animations

You can use a keyframe animation to change one or more control properties following a timeline. The keyframes are defined in Avalonia UI styles with cue points along the duration of the animation, and set the intermediate values of the properties at a point in time.

Diagram showing keyframe animation timeline with cue points

The property values between keyframes are set following the profile of an easing function. The default easing function is a straight-line interpolation.

The animation is triggered to start, and then can run any number of times, in either direction. There are also options to delay the start of the animation, and to repeat it.

In Avalonia, keyframe animations are defined using styles. See Styles for more information.

Animating a property​

To define a one-property animation on a control, such as a color fade:

  1. Create a styles collection at your chosen level.
  2. Add a style to the collection with a selector targeting the control.
  3. Add a Setter to define the property you want the animation to change, e.g., Fill in the below example.
  4. Add a Style.Animations tag for the animation itself.
  5. Add an Animation tag and set its Duration attribute. This is in the format "Hours:Minutes:Seconds".
  6. Define the keyframes for the animation. The below example uses cues at 0% and 100%.
  7. Each keyframe needs its own Setter to the value of the fill opacity.
<UserControl xmlns="https://github.com/avaloniaui">
  <UserControl.Styles>
    <Style Selector="Rectangle.blue">
      <Setter Property="Fill" Value="Blue"/>
        <Style.Animations>
          <Animation Duration="0:0:3"
                     IterationCount="infinite"> 
            <KeyFrame Cue="0%">
              <Setter Property="Opacity" Value="0.0"/>
            </KeyFrame>
            <KeyFrame Cue="100%">
              <Setter Property="Opacity" Value="1.0"/>
            </KeyFrame>
          </Animation>
        </Style.Animations>
    </Style>
  </UserControl.Styles>

  <Rectangle Classes="blue" Width="100" Height="100"/>
</UserControl>
Preview
Loading Avalonia Preview...

Animate two properties​

This example shows you how to animate two properties on one timeline. This time, the blue rectangle fades and rotates at the same time.

<UserControl xmlns="https://github.com/avaloniaui">
  <UserControl.Styles>
    <Style Selector="Rectangle.blue">
      <Setter Property="Fill" Value="Blue"/>
        <Style.Animations>
          <Animation Duration="0:0:3"
                     IterationCount="infinite">
            <KeyFrame Cue="0%">
              <Setter Property="Opacity" Value="0.0"/>
              <Setter Property="RotateTransform.Angle" Value="0.0"/>
            </KeyFrame>
            <KeyFrame Cue="100%"> 
              <Setter Property="Opacity" Value="1.0"/>
              <Setter Property="RotateTransform.Angle" Value="90.0"/>
            </KeyFrame>
          </Animation> 
        </Style.Animations>
    </Style>
  </UserControl.Styles>

  <Rectangle Classes="blue" Width="100" Height="100"/>
</UserControl>
Preview
Loading Avalonia Preview...

Configuring animation​

Delay​

You can add a delay to the start of an animation by setting the Delay attribute.

<Animation Duration="0:0:1"
           Delay="0:0:1"> 
    ...
</Animation>

Repeat​

You can make an animation repeat for a set number of times, or infinitely, by setting the IterationCount attribute.

<!-- Repeat 5 times -->
<Animation IterationCount="5">
    ...
</Animation>

<!-- Repeat indefinitely -->
<Animation IterationCount="infinite">
    ...
</Animation>

Playback direction​

By default, an animation plays forward, following the profile of the easing function from left to right. You can alter this behavior by setting the PlaybackDirection attribute.

<Animation Duration="0:0:1" PlaybackDirection="Reverse">
    ...
</Animation>

For a full list of PlaybackDirection options, see the animation settings reference.

Fill mode​

The fill mode attribute of an animation defines how the properties being set will persist after it runs, or during gaps between runs.

<Animation IterationCount="9" FillMode="Backward">
    ...
</Animation>

For a full list of FillMode options, see the animation settings reference.

Playback behavior​

By default, a keyframe animation pauses when its target control is not effectively visible. When the control becomes visible again, the animation resumes from where it paused.

You can change this behavior by setting the PlaybackBehavior attribute.

<Animation Duration="0:0:1" IterationCount="infinite" PlaybackBehavior="Always">
    ...
</Animation>

For a full list of PlaybackBehavior options, see the animation settings reference.

info

This playback behavior applies to keyframe animations only. Control transitions and composition animations are not affected.

Easing functions​

An easing function defines how a property is varied over time during an animation.

Graph showing linear easing function

The default easing function is linear (above). You can use another pattern by setting the name of the desired function in the Easing attribute. For example, to use the 'bounce ease in' function (below):

<Animation Duration="0:0:1"
           Delay="0:0:1"
           Easing="BounceEaseIn"> 
    ...
</Animation>
Graph showing bounce ease-in easing function

You can also create a custom easing function class and apply it like so:

<Animation Duration="0:0:1"
           Delay="0:0:1">
    <Animation.Easing>
        <local:YourCustomEasingClassHere/>
    </Animation.Easing> 
    ...
</Animation>

For a full list of easing functions, see the Easing functions page.

Running animations from code-behind​

For deeper control of the animation lifetime, you can define an animation as a Resource, so it can be used in the code-behind.

When defining an animation as a resource, you must set an x:Key to allow the animation to be accessed, as well as an x:SetterTargetType to specify the target control.

<Window xmlns="https://github.com/avaloniaui">
    <Window.Resources>
        <Animation x:Key="ResourceAnimation"
                   x:SetterTargetType="Rectangle"
                   Duration="0:0:3"> 
            <KeyFrame Cue="0%">
                <Setter Property="Opacity" Value="0.0"/>
            </KeyFrame>
            <KeyFrame Cue="100%">
                <Setter Property="Opacity" Value="1.0"/>
            </KeyFrame>
        </Animation>
    </Window.Resources>

    <Rectangle x:Name="Rect" />
</Window>

The ResourceAnimation defined above can now be accessed in a code-behind handler.

var animation = (Animation)this.Resources["ResourceAnimation"];
// Running XAML animation on the Rect control. 
await animation.RunAsync(Rect);

RunAsync returns a task which is completed when the animation ends. If an animation repeats infinitely, the task never ends, unless (1) the RunAsync method is cancelled by a CancellationToken, or (2) the target control is detached from the visual tree.

See also​

On this page