Skip to content

1079 update animation docs include new v12 changes to the control visibility logic #1129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
luke-whos-here wants to merge 4 commits into
base: main
Choose a base branch
from
Open

1079 update animation docs include new v12 changes to the control visibility logic #1129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cbdae18
Document playback behavior on main relevant pages
luke-whos-here Aug 28, 2026
cc8522a
Edit animations page
luke-whos-here Aug 28, 2026
1b55366
Add references and notes on related pages
luke-whos-here Aug 28, 2026
a03c7ab
Address Copilot comments
luke-whos-here Sep 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/app-development/performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,9 @@ myControl2.Height = 200;

### Hiding unused controls with `IsVisible`

Setting `IsVisible="False"` removes a control from both layout and rendering. The layout system skips the measure and arrange passes for that control and its entire subtree, and the renderer does not draw it. This makes `IsVisible` an effective way to reduce work for conditionally shown content:
Setting `IsVisible="False"` can reduce work for conditionally shown content by removing a control from both layout and rendering. The layout system skips the measure and arrange passes for that control and its entire subtree, and the renderer does not draw it.

In addition, hiding a control also pauses any [keyframe animations](/docs/graphics-animation/keyframe-animations#playback-behavior) running on it or its subtree by default, which stops them from waking the CPU on an idle UI.

```xml
<Panel>
Expand All @@ -190,7 +192,7 @@ Setting `IsVisible="False"` removes a control from both layout and rendering. Th
</Panel>
```

If you need to hide a control visually while keeping its layout space reserved, use `Opacity="0"` instead. An element with `Opacity="0"` still participates in layout and can receive input.
If you need to hide a control visually while keeping its layout space reserved, use `Opacity="0"` instead. An element with `Opacity="0"` still participates in layout, can receive input, and its keyframe animations continue playing.

### Using `ClipToBounds` judiciously

Expand Down
46 changes: 28 additions & 18 deletions docs/graphics-animation/animation-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ This section describes how `Animation` playback can be customized.

## Easing functions

`Easing` functions describe how quickly an animated property changes from its starting value into its ending value across the animation time. `Avalonia.Animation.Easings` contains the following easings:
Easing functions describe how quickly an animated property changes from its starting value into its ending value across the animation time. `Avalonia.Animation.Easings` contains the following easings:

| Default |
|---------------------------------------------------------------|
Expand All @@ -62,38 +62,48 @@ This section describes how `Animation` playback can be customized.

Additionally, you can provide your own easing by deriving from `Easing` or by providing parameters to `SplineEasing` or `SpringEasing`.

## FillModes
## Fill mode

The `FillMode` attribute of an `Animation` defines how the animated property persists after an animation completes and during delays in-between runs.

The following table describes the supported behaviors:
The `FillMode` attribute of an `Animation` defines how the animated property persists after an animation completes and during delays in between runs.

| Value | Description |
|------------|-----------------------------------------------------------------------------------------------------------|
| `None` | Value will not persist after animation nor the first value will be applied when the animation is delayed. |
| `Forward` | The last interpolated value will be persisted to the target property. |
| `Backward` | The first interpolated value will be displayed on animation delay. |
| `Both` | Both `Forward` and `Backward` behaviors will be applied. |
| `None` | Last value does not persist after animation. First value is not applied if the animation is delayed. |
| `Forward` | The last interpolated value is persisted after the animation ends. |
| `Backward` | The first interpolated value is displayed if the animation is delayed. |
| `Both` | Both `Forward` and `Backward` behaviors are applied. |

## PlaybackDirection
## Playback direction

`PlaybackDirection` defines how the `Animation` will be played. The following table describes the possible settings:
`PlaybackDirection` defines how the `Animation` is played. By default, an animation plays forward, following the profile of the easing function from left to right.

| Value | Description |
|--------------------|---------------------------------------------------------|
| `Normal` | The animation is played normally. |
| `Reverse` | The animation is played in reverse direction. |
| `Alternate` | The animation is played forwards first, then backwards. |
| `AlternateReverse` | The animation is played backwards first, then forwards. |
| `Normal` | (Default) Played forward. |
| `Reverse` | Played backward. |
| `Alternate` | Played forward first, then backward. |
| `AlternateReverse` | Played backward first, then forward. |

## 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.

This behavior is intended to avoid waking the CPU to run animations the user cannot see. A control becomes effectively invisible when `IsVisible` is `false` on the control itself, or when an ancestor is hidden.

| Value | Description |
| ----------------| ----------------------- |
| `Auto` | (Default) Animation pauses when the control is not effectively visible. Animations started with `RunAsync`, or containing keyframes where `IsVisible="True"`, always play regardless of visibility. |
| `Always` | Animation always plays, regardless of visibility. |
| `OnlyIfVisible` | Animation always pauses when the control is not effectively visible, even if started with `RunAsync`. |

## IterationCount
## Iteration count

The `IterationCount` on an `Animation` element sets how many times it is to be replayed. There are two formats for this setting:

| Value | Description |
|------------|--------------------------------------------------|
| `N` | (N is an integer) - play N times. N can be zero. |
| `Infinite` | Repeats forever |
| `N` | Where N is an integer. Play N times. N can be zero. |
| `infinite` | Repeats forever. |

## See also

Expand Down
37 changes: 26 additions & 11 deletions docs/graphics-animation/animations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,21 +91,35 @@ See [Composition Animations](/docs/graphics-animation/composition-animations) fo
Keyframe animations defined in XAML rely on style selectors for their triggering behavior:

- **Unconditional selector** (e.g., `Style Selector="Border"`): The animation starts when the control enters the visual tree.
- **Conditional selector** (e.g., `Style Selector="Border:pointerover"`): The animation runs when the selector matches (pointer is over the border) and stops when it no longer matches.
- **Conditional selector** (e.g., `Style Selector="Border:pointerover"`): The animation runs when the selector condition matches (e.g., pointer is over the border) and stops when it no longer matches.

<XamlPreview>

```xml
<Style Selector="Border:pointerover">
<Style.Animations>
<Animation Duration="0:0:0.3">
<UserControl xmlns="https://github.com/avaloniaui">
<UserControl.Styles>
<Style Selector="Border:pointerover">
<Style.Animations>
<Animation Duration="0:0:2">
<KeyFrame Cue="100%">
<Setter Property="ScaleTransform.ScaleX" Value="1.1" />
<Setter Property="ScaleTransform.ScaleY" Value="1.1" />
<Setter Property="ScaleTransform.ScaleX" Value="1.5" />
<Setter Property="ScaleTransform.ScaleY" Value="1.5" />
</KeyFrame>
</Animation>
</Style.Animations>
</Style>
</Style.Animations>
</Style>
</UserControl.Styles>

<Border Width="100" Height="100" Background="blue" />
</UserControl>
```

</XamlPreview>

:::info
By default, a style-applied keyframe animation pauses when its control is effectively invisible, and resumes when the control is visible again. See [Playback behavior](/docs/graphics-animation/keyframe-animations#playback-behavior).
:::

## Animation settings

Keyframe animations support these configuration options:
Expand All @@ -114,10 +128,11 @@ Keyframe animations support these configuration options:
|---|---|---|
| `Duration` | How long one cycle takes. | `0:0:1` (1 second) |
| `Delay` | Time to wait before starting. | `0:0:0.5` |
| `IterationCount` | Number of times to repeat. Use `INFINITE` for forever. | `3`, `INFINITE` |
| `PlaybackDirection` | Direction of playback. | `Normal`, `Reverse`, `Alternate`, `AlternateReverse` |
| `FillMode` | What happens when the animation ends. | `Forward`, `Backward`, `Both`, `None` |
| `Easing` | The interpolation curve between keyframes. | `CubicEaseInOut` |
| `FillMode` | What happens when the animation ends. | `Forward`, `Backward`, `Both`, `None` |
| `IterationCount` | Number of times to repeat. Use `infinite` for forever. | `3`, `INFINITE` |
| `PlaybackBehavior` | Whether to pause the animation when the control is hidden. | `Normal`, `Reverse`, `Alternate`, `AlternateReverse` |
| `PlaybackDirection` | Direction of playback. | `Auto`, `Always`, `OnlyIfVisible` |

See [Animation Settings](/docs/graphics-animation/animation-settings) for details on each option and [Easing Functions](/docs/graphics-animation/easing-functions) for all available easing types.

Expand Down
6 changes: 5 additions & 1 deletion docs/graphics-animation/control-transitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,11 @@ description: Configure transitions that animate property changes on Avalonia con
doc-type: how-to
---

Transitions in Avalonia are also heavily inspired by CSS Animations. They listen to any changes in target property's value and subsequently animates the change according to its parameters. They can be defined on any `Control` via the [`Transitions`](/api/avalonia/animation/transitions) property:
Transitions in Avalonia are also heavily inspired by CSS Animations. They listen to any changes in target property's value and subsequently animate the change according to its parameters. They can be defined on any `Control` via the [`Transitions`](/api/avalonia/animation/transitions) property.

:::note
Unlike [keyframe animations](/docs/graphics-animation/keyframe-animations), transitions do not pause on hidden controls.
:::

## Basic usage

Expand Down
8 changes: 4 additions & 4 deletions docs/graphics-animation/effects.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,10 +238,10 @@ Values range from `0.0` (fully transparent) to `1.0` (fully opaque). Unlike `Opa

### IsVisible vs Opacity

| Approach | Layout impact | Interaction |
|---|---|---|
| `IsVisible="False"` | Element is removed from layout. | Cannot receive input. |
| `Opacity="0"` | Element still occupies space. | Can still receive pointer and keyboard input. |
| Approach | Layout impact | Interaction | Animations |
| --- | --- | --- | --- |
| `IsVisible="False"` | Element is removed from layout. | Cannot receive input. | [Keyframe animations](/docs/graphics-animation/keyframe-animations) pause by default. |
| `Opacity="0"` | Element still occupies space. | Can still receive pointer and keyboard input. | [Keyframe animations](/docs/graphics-animation/keyframe-animations) keep running. |

## Animating effects

Expand Down
Loading
Loading