|
| 1 | +--- |
| 2 | +description: An AnimatedIcon is a control which plays animated images in response to user interaction and visual state changes. |
| 3 | +title: AnimatedIcon |
| 4 | +template: detail.hbs |
| 5 | +ms.date: 3/12/2021 |
| 6 | +ms.topic: article |
| 7 | +keywords: windows 10, winui, uwp |
| 8 | +pm-contact: mamatth |
| 9 | +design-contact: albeyih |
| 10 | +dev-contact: ranjeshj |
| 11 | +ms.custom: 20H2 |
| 12 | +ms.localizationpriority: medium |
| 13 | +--- |
| 14 | + |
| 15 | +# AnimatedIcon |
| 16 | + |
| 17 | +An AnimatedIcon control plays animated images in response to user interaction and visual state changes. |
| 18 | + |
| 19 | +Animated icons can draw attention to a UI component, such as the next button in a tutorial, or simply reflect the action associated with the icon in an entertaining and interesting way. |
| 20 | + |
| 21 | +Custom animations can be created with [Adobe AfterEffects](https://www.adobe.com/products/aftereffects.html) and rendered with the [Lottie-Windows](/windows/communitytoolkit/animations/lottie) library to use as an animated icon in your WinUI application. For more detail, see [Use Lottie to create animated content for an AnimatedIcon](#use-lottie-to-create-animated-content-for-an-animatedicon) later in this article. |
| 22 | + |
| 23 | +The following example shows a basic animated search icon that was created in Adobe AfterEffects and rendered through Lottie. |
| 24 | + |
| 25 | +:::image type="content" source="images/animated_search.gif" alt-text="An animated search icon"::: |
| 26 | + |
| 27 | +## Is this the right control? |
| 28 | + |
| 29 | +Use the AnimatedIcon control when a control's icon needs to animate in response to user interaction with the control, such as when a user hovers over a button or clicks it. |
| 30 | + |
| 31 | +Do not use an AnimatedIcon if the animation is not triggered by a visual state transition, and plays in a loop, plays one time only, or can be paused. Use AnimatedVisualPlayer instead. |
| 32 | + |
| 33 | +Do not use AnimatedIcon for anything other than an icon, or where the control does not support an IconElement or IconElementSource property. Use AnimatedVisualPlayer instead. |
| 34 | + |
| 35 | +When an animated icon is not required, use [FontIcon](/uwp/api/windows.ui.xaml.controls.fonticon), [SymbolIcon](/uwp/api/windows.ui.xaml.controls.symbolicon), or [BitmapIcon](/uwp/api/windows.ui.xaml.controls.bitmapicon) instead. |
| 36 | + |
| 37 | +### Differences between AnimatedIcon and AnimatedVisualPlayer |
| 38 | + |
| 39 | +AnimatedIcon is an [IconElement](/windows/winui/api/microsoft.ui.xaml.controls.iconelement), which can be used anywhere an element or IconElement is required (such as [NavigationViewItem.Icon](/windows/winui/api/microsoft.ui.xaml.controls.navigationviewitem.icon)), and is controlled through a State property. |
| 40 | + |
| 41 | +[AnimatedVisualPlayer](https://docs.microsoft.com/uwp/api/Microsoft.UI.Xaml.Controls.AnimatedVisualPlayer) is a more general animation player, that is controlled through methods such as Play and Pause, and can be used anywhere in an application. |
| 42 | + |
| 43 | +**Get the Windows UI Library** |
| 44 | + |
| 45 | +:::row::: |
| 46 | + :::column::: |
| 47 | +  |
| 48 | + :::column-end::: |
| 49 | + :::column span="3"::: |
| 50 | + The **AnimatedIcon** control requires the Windows UI Library, a NuGet package that contains new controls and UI features for Windows apps. For more info, including installation instructions, see [Windows UI Library](/uwp/toolkits/winui/). |
| 51 | + :::column-end::: |
| 52 | + :::column::: |
| 53 | + |
| 54 | + :::column-end::: |
| 55 | +:::row-end::: |
| 56 | + |
| 57 | +> **Windows UI Library APIs:** [AnimatedIcon class](/uwp/api/microsoft.ui.xaml.controls.animated-icon) |
| 58 | +
|
| 59 | +> [!TIP] |
| 60 | +> Throughout this document, we use the **muxc** alias in XAML to represent the Windows UI Library APIs that we have included in our project. We have added this to our [Page](/uwp/api/windows.ui.xaml.controls.page) element: `xmlns:muxc="using:Microsoft.UI.Xaml.Controls"` |
| 61 | +> |
| 62 | +> In the code-behind, we also use the **muxc** alias in C# to represent the Windows UI Library APIs that we have included in our project. We have added this **using** statement at the top of the file: `using muxc = Microsoft.UI.Xaml.Controls;` |
| 63 | +
|
| 64 | +## Use Lottie to create animated content for an AnimatedIcon |
| 65 | + |
| 66 | +Defining an animation for an AnimatedIcon begins the same as the process to define an animation for an AnimatedVisualPlayer. You must create, or obtain, the Lottie file for the icon you want to add and run that file through [LottieGen](/windows/communitytoolkit/animations/lottie-scenarios/getting_started_codegen). LottieGen generates code for a C++/WinRT class that you can then instantiate and use with an AnimatedIcon. |
| 67 | + |
| 68 | +> [!NOTE] |
| 69 | +> The [AutoSuggestBox](/windows/winui/api/microsoft.ui.xaml.controls.autosuggestbox) control uses the [AnimatedVisuals.AnimatedFindVisualSource](/windows/winui/api/microsoft.ui.xaml.controls.animatedvisuals.animatedfindvisualsource) class, which was generated using the LottieGen tool. |
| 70 | +
|
| 71 | +You can also define markers in the animation definition to indicate playback time positions. You can then set the AnimatedIcon state to these markers. For example, if you have a playback position in the Lottie file marked "PointerOver", you can set the AnimatedIcon state to "PointerOver" and move the animation to that playback position. |
| 72 | + |
| 73 | +Defining a color property in your Lottie animation named "Foreground" lets you to set the color using the AnimatedIcon.Foreground property. |
| 74 | + |
| 75 | +## Examples |
| 76 | + |
| 77 | +<table> |
| 78 | +<th align="left">XAML Controls Gallery<th> |
| 79 | +<tr> |
| 80 | +<td><img src="images/xaml-controls-gallery-app-icon-sm.png" alt="XAML controls gallery"></img></td> |
| 81 | +<td> |
| 82 | + <p>If you have the <strong style="font-weight: semi-bold">XAML Controls Gallery</strong> app installed, click here to <a href="xamlcontrolsgallery:/item/AnimatedIcon">open the app and see the InfoBar in action</a>.</p> |
| 83 | + <ul> |
| 84 | + <li><a href="https://www.microsoft.com/store/productId/9MSVH128X2ZT">Get the XAML Controls Gallery app (Microsoft Store)</a></li> |
| 85 | + <li><a href="https://github.com/Microsoft/Xaml-Controls-Gallery">Get the source code (GitHub)</a></li> |
| 86 | + </ul> |
| 87 | +</td> |
| 88 | +</tr> |
| 89 | +</table> |
| 90 | + |
| 91 | +### Add an AnimatedIcon to a Button |
| 92 | + |
| 93 | +The following example demonstrates a back button that displays an animated back icon on a [PointerEntered](/windows/winui/api/microsoft.ui.xaml.uielement.pointerentered) event. |
| 94 | + |
| 95 | +- The `AnimatedBackVisualSource` is a class created with the [LottieGen](https://github.com/windows-toolkit/Lottie-Windows/tree/master/LottieGen) command line tool. |
| 96 | +- The FallbackIconSource is used when animations can't be played, such as on older versions of Windows that don't support Lottie animations. |
| 97 | +- If the user turns animations off in their system settings, AnimatedIcon displays the final frame of the state transition the controls was in. |
| 98 | + |
| 99 | +```xaml |
| 100 | +<Button PointerEntered="Button_PointerEntered" PointerExited="Button_PointerExited"> |
| 101 | + <muxc:AnimatedIcon x:Name='BackAnimatedIcon'> |
| 102 | + <muxc:AnimatedIcon.Source> |
| 103 | + <animatedvisuals:AnimatedBackVisualSource/> |
| 104 | + </muxc:AnimatedIcon.Source> |
| 105 | + <muxc:AnimatedIcon.FallbackIconSource> |
| 106 | + <muxc:SymbolIconSource Symbol='Back'/> |
| 107 | + </muxc:AnimatedIcon.FallbackIconSource> |
| 108 | + </muxc:AnimatedIcon> |
| 109 | +</Button> |
| 110 | +``` |
| 111 | + |
| 112 | +```cs |
| 113 | +private void Button_PointerEntered(object sender, PointerRoutedEventArgs e) |
| 114 | +{ |
| 115 | + AnimatedIcon.SetState(this.BackAnimatedIcon, "PointerOver"); |
| 116 | +} |
| 117 | + |
| 118 | +private void Button_PointerExited(object sender, PointerRoutedEventArgs e) |
| 119 | +{ |
| 120 | + AnimatedIcon.SetState(this.BackAnimatedIcon, "Normal"); |
| 121 | +} |
| 122 | +``` |
| 123 | + |
| 124 | +### Add an AnimatedIcon to NavigationViewItem |
| 125 | + |
| 126 | +The NavigationViewItem control automatically sets common states on an AnimatedIcon based on the state of the control, if those markers are defined in the Lottie animation. |
| 127 | + |
| 128 | +For example, the following example shows how to set a custom animation (`GameSettingsIcon`) that was generated by the LottieGen tool: |
| 129 | + |
| 130 | +```xaml |
| 131 | +<muxc:NavigationView.MenuItems> |
| 132 | + <muxc:NavigationViewItem Content = "Game Settings"> |
| 133 | + <muxc:NavigationViewItem.Icon> |
| 134 | + <muxc:AnimatedIcon x:Name='GameSettingsIcon'> |
| 135 | + <muxc:AnimatedIcon.Source> |
| 136 | + <animatedvisuals:AnimatedSettingsVisualSource/> |
| 137 | + </muxc:AnimatedIcon.Source> |
| 138 | + <muxc:AnimatedIcon.FallbackIconSource> |
| 139 | + <muxc:FontIconSource FontFamily="Segoe MDL2 Assets" Glyph=""/> |
| 140 | + </muxc:AnimatedIcon.FallbackIconSource> |
| 141 | + </muxc:AnimatedIcon> |
| 142 | + </muxc:NavigationViewItem.Icon> |
| 143 | + </muxc:NavigationViewItem> |
| 144 | +</muxc:NavigationView.MenuItems> |
| 145 | +``` |
| 146 | + |
| 147 | + |
| 148 | + |
| 149 | +The NavigationViewItem automatically sets the following states on the AnimatedIcon: |
| 150 | + |
| 151 | +- Normal |
| 152 | +- PointerOver |
| 153 | +- Pressed |
| 154 | +- Selected |
| 155 | +- PressedSelected |
| 156 | +- PointerOverSelected |
| 157 | + |
| 158 | +If `GameSettingsIcon` has a marker defined for "NormalToPointerOver", the icon will be animated until the pointer moves over the NavigationViewItem. See the following section for more information on creating markers. |
| 159 | + |
| 160 | +## Define AnimatedIcon markers |
| 161 | + |
| 162 | +To create the custom `GameSettingsIcon` in the previous example, run a Lottie JSON file (with markers) through the Windows [LottieGen](https://docs.microsoft.com/windows/communitytoolkit/animations/lottie-scenarios/getting_started_codegen) tool to generate the animation code as a C# class. |
| 163 | + |
| 164 | +Once you run your Lottie file through LottieGen you can add the CodeGen output class to your project. See the [LottieGen](https://docs.microsoft.com/windows/communitytoolkit/animations/lottie-scenarios/getting_started_codegen) tutorial for more information. |
| 165 | + |
| 166 | +Setting the AnimatedIcon state to a new value also sets a playback position in the Lottie animation for the transition from the old state to the new state. These playback positions are also identified with markers in the Lottie file. Specific markers for the start of the transition or the end of the transition can also be defined. |
| 167 | + |
| 168 | +For example, the [AutoSuggestBox](/windows/winui/api/microsoft.ui.xaml.controls.autosuggestbox) control uses an AnimatedIcon that animates with the following states: |
| 169 | + |
| 170 | +- Normal |
| 171 | +- PointerOver |
| 172 | +- Pressed |
| 173 | + |
| 174 | +You can define markers in your Lottie file with those state names. You can also define markers as follows: |
| 175 | + |
| 176 | +- Insert "To" between state names. For example, if you define a "NormalToPointerOver" marker, changing the AnimatedIcon state from "Normal" to "PointerOver" will cause it to move to this marker's playback position. |
| 177 | +- Append "_Start" or "_End" to a marker name. For example defining markers "NormalToPointerOver_Start" and "NormalToPointerOver_End" and changing the AnimatedIcon state from "Normal" to "PointerOver" will cause it to jump to the _Start marker's playback position and then animate to the _End playback position. |
| 178 | + |
| 179 | +The exact algorithm used to map AnimatedIcon State changes to marker playback positions: |
| 180 | + |
| 181 | +- Check the provided file's markers for the markers "[PreviousState]To[NewState]_Start" and "[PreviousState]To[NewState]_End". If both are found play the animation from "[PreviousState]To[NewState]_Start" to "[PreviousState]To[NewState]_End". |
| 182 | +- If "[PreviousState]To[NewState]_Start" is not found but "[PreviousState]To[NewState]_End" is found, then hard cut to the "[PreviousState]To[NewState]_End" playback position. |
| 183 | +- If "[PreviousState]To[NewState]_End" is not found but "[PreviousState]To[NewState]_Start" is found, then hard cut to the "[PreviousState]To[NewState]_Start" playback position. |
| 184 | +- Check if the provided IAnimatedVisualSource2's markers for the marker "[PreviousState]To[NewState]". If it is found then hard cut to the "[PreviousState]To[NewState]" playback position. |
| 185 | +- Check if the provided IAnimatedVisualSource2's markers for the marker "[NewState]". If it is found, then hard cut to the "[NewState]" playback position. |
| 186 | +- Check if the provided IAnimatedVisualSource2's markers has any marker which ends with "To[NewState]_End". If any marker is found which has that ending, hard cut to the first marker found with the appropriate ending's playback position. |
| 187 | +- Check if "[NewState]" parses to a float. If it does, animated from the current position to the parsed float. |
| 188 | +- Hard cut to playback position 0.0. |
| 189 | + |
| 190 | +The following example shows the marker format in a Lottie JSON file. See the [AnimatedIcon](/windows/uwp/design/motion/animatedicons) guidance for more detail. |
| 191 | + |
| 192 | +```json |
| 193 | +"markers":[{"tm":0,"cm":"NormalToPointerOver_Start","dr":0},{"tm":9,"cm":"NormalToPointerOver_End","dr":0}, |
| 194 | + |
| 195 | +{"tm":10,"cm":"NormalToPressed_Start","dr":0},{"tm":19,"cm":"NormalToPressed_End","dr":0}, |
| 196 | + |
| 197 | +{"tm":20,"cm":"PointerOverToNormal_Start","dr":0},{"tm":29,"cm":"PointerOverToNormal_End","dr":0}, |
| 198 | + |
| 199 | +{"tm":30,"cm":"PointerOverToPressed_Start","dr":0},{"tm":39,"cm":"PointerOverToPressed_End","dr":0}, |
| 200 | + |
| 201 | +{"tm":40,"cm":"PressedToNormal_Start","dr":0},{"tm":49,"cm":"PressedToNormal_End","dr":0}, |
| 202 | + |
| 203 | +{"tm":50,"cm":"PressedToPointerOver_Start","dr":0},{"tm":69,"cm":"PressedToPointerOver_End","dr":0}, |
| 204 | + |
| 205 | +{"tm":90,"cm":"PressedToNormal_Start","dr":0},{"tm":99,"cm":"PressedToNormal_End","dr":0}, |
| 206 | + |
| 207 | +{"tm":100,"cm":"PressedToPointerOver_Start","dr":0},{"tm":101,"cm":"PressedToPointerOver_End","dr":0}] |
| 208 | +``` |
| 209 | + |
| 210 | +### Adding a Standalone AnimatedIcon |
| 211 | + |
| 212 | +The following example is a button that the user clicks to Accept a prompt. |
| 213 | + |
| 214 | +The `MyAcceptAnimation` class is created with the [LottieGen](https://docs.microsoft.com/windows/communitytoolkit/animations/lottie-scenarios/getting_started_codegen) tool. |
| 215 | + |
| 216 | +The FallbackIconSource will be used rather than the animation when animations can't be played, such as on older versions of Windows that don't support Lottie animations. |
| 217 | + |
| 218 | +If the end user turns off animations in their system settings, AnimatedIcon will display the final frame of the state transition the controls was in. |
| 219 | + |
| 220 | +```xml |
| 221 | +<Button PointerEntered="HandlePointerEntered" PointerExited="HandlePointerExited"> |
| 222 | + <muxc:AnimatedIcon x:Name='AnimatedIcon1'> |
| 223 | + <local:MyAcceptAnimation/> |
| 224 | + <muxc:AnimatedIcon.FallbackIconSource> |
| 225 | + <muxc:SymbolIconSource Symbol='Accept'/> |
| 226 | + </muxc:AnimatedIcon.FallbackIconSource> |
| 227 | + </muxc:AnimatedIcon> |
| 228 | +</Button> |
| 229 | +``` |
| 230 | + |
| 231 | +```cs |
| 232 | +private void Button_PointerEntered(object sender, PointerRoutedEventArgs e) |
| 233 | +{ |
| 234 | + AnimatedIcon.SetState(this.AnimatedIcon1, "PointerOver"); |
| 235 | +} |
| 236 | + |
| 237 | +private void Button_PointerExited(object sender, PointerRoutedEventArgs e) |
| 238 | +{ |
| 239 | + AnimatedIcon.SetState(this.StackPaAnimatedIcon1nel1, "Normal"); |
| 240 | +} |
| 241 | +``` |
| 242 | + |
| 243 | +## Recommendations |
| 244 | + |
| 245 | +- Please view the UX guidance for [Icons for Windows Apps](/windows/uwp/design/style/icons) to ensure your icons match the design principles. |
| 246 | +- Limit the number of animated icons on a single screen or view. Only animate icons to draw the user's attention to where they need to take action or when they are performing an action. |
| 247 | + |
| 248 | +## Related articles |
| 249 | + |
| 250 | +- [Icons](/windows/uwp/design/style/icons) |
| 251 | +- [Animations in XAML](/windows/uwp/design/motion/xaml-animation) |
0 commit comments