General Principles

Just like building UIs with ComponentKit might require a slightly different way of thinking compared to traditional iOS UI frameworks, the same principle applies to animations.

Generally, all changes to your UI should be done via state or props updates instead of mutating view attributes directly. Similarly, animations in ComponentKit are only triggered by regenerating a component tree, so there has to be a state or props update. You should avoid reaching out to a component view and applying animations to it or its layer directly because component views are managed by CK infra and your changes are not guaranteed to be preserved. In addition to that, you risk introducing inconsistencies between animation values and the current values of the animated properties which will result in "jumps" and other visual artefacts.

In the majority of the cases, you should be doing one of three things below:

  • animate from a given value to the value specified in the view configuration

  • animate from the value specified in the view configuration to a given value

  • animate between values specified in the view configurations of a different generations of a given component

On the code level this translates to you specifying either:

  • the initial value for an animated property (often referred to as from value)

  • the final value for an animated property (to value)

  • no values at all, since they will be inferred from the view configuration

Specifying both initial and final values is usually a sign that you're doing more work than necessary or even introducing a bug.

Another way to think about this is that only view configuration is permanent and animation values are temporary. A common mistake is to make animation values "permanent" by using a forwards fill mode and setting removedOnCompletion property to false, which causes animated values to override the values in the model layer. In addition to writing more code, this also increases the load on the render server process by keeping these animations around thus affecting performance. In the vast majority of the cases this wouldn't be an issue if you make sure to have the right values in the view configuration.

The rest of this document will demonstrate how to apply these principles when writing animation code for your components.