Skip to content

CATransaction ​

CATransaction represents a transaction: a group of layer changes handed to the system together. It controls the implicit animations of those changes: turning them off, or changing their duration and timing curve.

CATransaction has no instances; everything is a static method. begin() and commit() come in pairs, and settings made between them apply only to the changes in between; after commit(), things return to how they were.

Inheritance: CATransaction. It doesn't inherit from NSObject and isn't an EventTarget.

For when to turn off implicit animations and when to create your own animation objects, see the guide Turning off implicit animations.

Constructor ​

Can't be created with new. new CATransaction() throws TypeError: Illegal constructor: CATransaction is a set of class methods, not an object.

Static methods ​

Starting and ending a transaction:

MethodDescription
CATransaction.begin()Starts a transaction
CATransaction.commit()Ends the most recently started transaction
CATransaction.flush()Hands the layer changes made so far to the system immediately

Settings of the current transaction, each with a getter and a setter:

MethodDescription
CATransaction.disableActions()Whether the current transaction has implicit animations turned off
CATransaction.setDisableActions()Turns implicit animations off or on for the current transaction
CATransaction.animationDuration()The implicit animation duration of the current transaction
CATransaction.setAnimationDuration()Sets the implicit animation duration of the current transaction
CATransaction.animationTimingFunction()The timing curve used by the current transaction's implicit animations
CATransaction.setAnimationTimingFunction()Sets the timing curve used by the current transaction's implicit animations

Implicit animations ​

Once a layer created with new has been shown on screen, changing its properties doesn't jump straight to the new value. The system automatically adds a transition animation; this is called an implicit animation. The duration is the iOS default of 0.25 seconds (the duration is not verified in the simulator).

js
const shape = new CAShapeLayer();
// ...shape is already shown on screen
shape.strokeEnd = 0.5;
console.log(shape.animationKeys());

Result: after the layer has been shown, the logged array contains 'strokeEnd': this assignment made the system add an animation to the layer, named after the property.

Whether an implicit animation occurs, as measured:

When the property changesImplicit animation?
The layer hasn't been added to a parent layer yetNo
The layer has been added but not shown yetNo
The layer has been shownYes
A view's own layer (view.layer)No. Not verified in the simulator

When you build the whole UI in one go in the sceneconnect callback, no layer has been shown yet, so property changes all take effect immediately. Only later changes, in tap callbacks or timer callbacks, come with a transition.

Rules of transactions:

  • Transactions can be nested. Settings not made in the inner one are inherited from the outer one. Nesting is not verified in the simulator.
  • The settings affect only implicit animations. Animations added with addAnimation() are not affected by setDisableActions(true) and play as usual.

Examples ​

js
const shape = new CAShapeLayer();

CATransaction.begin();
CATransaction.setDisableActions(true);
shape.strokeEnd = 1;
CATransaction.commit();

Effect: strokeEnd becomes 1 immediately, and no new animation is added to the layer.

Corresponding iOS API ​

ObjCJS
[CATransaction begin] / [CATransaction commit]CATransaction.begin() / CATransaction.commit()
[CATransaction setDisableActions:YES]CATransaction.setDisableActions(true)
[CATransaction setAnimationDuration:1.5]CATransaction.setAnimationDuration(1.5)

See also ​