SwiftUI Animation
Overview
Comprehensive guide to SwiftUI's animation system, from foundational concepts to advanced techniques. This skill covers the Animatable protocol, the iOS 26 @Animatable macro, animation types, and the Transaction system.
Core principle Animation in SwiftUI is mathematical interpolation over time, powered by the VectorArithmetic protocol. Understanding this foundation unlocks the full power of SwiftUI's declarative animation system.
System Requirements
- iOS 13+: Animatable protocol, timing/spring animations
- iOS 17+: Default spring animations, scoped animations, PhaseAnimator, KeyframeAnimator
- iOS 18+: Zoom transitions, UIKit/AppKit animation bridging
- iOS 26+: @Animatable macro
Part 1: Understanding Animation
What Is Interpolation
Animation is the process of generating intermediate values between a start and end state.
Example: Opacity animation
.opacity(0) → .opacity(1)
While this animation runs, SwiftUI computes intermediate values:
0.0 → 0.02 → 0.05 → 0.1 → 0.25 → 0.4 → 0.6 → 0.8 → 1.0
How values are distributed
- Determined by the animation's timing curve or velocity function
- Spring animations use physics simulation
- Timing curves use bezier curves
- Each animation type calculates values differently
VectorArithmetic Protocol
SwiftUI requires animated data to conform to VectorArithmetic — providing subtraction, scaling, addition, and a zero value. This enables SwiftUI to interpolate between any two values.
Built-in conforming types: CGFloat, Double, Float, Angle (1D), CGPoint, CGSize (2D), CGRect (4D).
Key insight Vector arithmetic abstracts over dimensionality. SwiftUI animates all these types with a single generic implementation.
Why Int Can't Be Animated
Int doesn't conform to VectorArithmetic — no fractional intermediates exist between 3 and 4. SwiftUI simply snaps the value.
Solution: Use Float/Double and display as Int:
@State private var count: Float = 0
Text("\(Int(count))")
.animation(.spring, value: count)
Model vs Presentation Values
Animatable attributes conceptually have two values:
Model Value
- The target value set by your code
- Updated immediately when state changes
- What you write in your view's body
Presentation Value
- The current interpolated value being rendered
- Updates frame-by-frame during animation
- What the user actually sees
Example
.scaleEffect(selected ? 1.5 : 1.0)
When selected becomes true:
- Model value: Immediately becomes
1.5
- Presentation value: Interpolates
1.0 → 1.1 → 1.2 → 1.3 → 1.4 → 1.5 over time
Part 2: Animatable Protocol
Overview
The Animatable protocol allows views to animate their properties by defining which data should be interpolated.
protocol Animatable {
associatedtype AnimatableData: VectorArithmetic
var animatableData: AnimatableData { get set }
}
SwiftUI builds an animatable attribute for any view conforming to this protocol.
Built-in Animatable Views
Many SwiftUI modifiers conform to Animatable:
Visual Effects
.scaleEffect() — Animates scale transform.rotationEffect() — Animates rotation.offset() — Animates position offset.opacity() — Animates transparency.blur() — Animates blur radius.shadow() — Animates shadow properties
All Shape types
Circle, Rectangle, RoundedRectangleCapsule, Ellipse, Path- Custom
Shape implementations
AnimatablePair for Multi-Dimensional Data
When animating multiple properties, use AnimatablePair to combine vectors. For example, scaleEffect combines CGSize (2D) and UnitPoint (2D) into a 4D vector via AnimatablePair<CGSize.AnimatableData, UnitPoint.AnimatableData>. Access components via .first and .second. The @Animatable macro (iOS 26+) eliminates this boilerplate entirely.
Custom Animatable Conformance
When to use
- Animating custom layout (like RadialLayout)
- Animating custom drawing code
- Animating properties that affect shape paths
Example: Animated number view
struct AnimatableNumberView: View, Animatable {
var number: Double
var animatableData: Double {
get { number }
set { number = newValue }
}
var body: some View {
Text("\(Int(number))")
.font(.largeTitle)
}
}
AnimatableNumberView(number: value)
.animation(.spring, value: value)
How it works
number changes from 0 to 100- SwiftUI calls
body for every frame of the animation
- Each frame gets a new
number value: 0 → 5 → 15 → 30 → 55 → 80 → 100
- Text updates to show the interpolated integer
Performance Warning
Custom Animatable conformance is expensive — SwiftUI calls body for every frame on the main thread. Built-in effects (.scaleEffect(), .opacity()) run off-main-thread and don't call body. Use custom conformance only when built-in modifiers can't achieve the effect (e.g., animating a custom Layout that repositions subviews per-frame).
Part 3: @Animatable Macro (iOS 26+)
Overview
The @Animatable macro eliminates the boilerplate of manually conforming to the Animatable protocol.
Before iOS 26, you had to:
- Manually conform to
Animatable
- Write
animatableData getter and setter
- Use
AnimatablePair for multiple properties
- Exclude non-animatable properties manually
iOS 26+, you just add @Animatable:
@MainActor
@Animatable
struct MyView: View {
var scale: CGFloat
var opacity: Double
var body: some View {
}
}
The macro automatically:
- Generates
Animatable conformance
- Inspects all stored properties
- Creates
animatableData from VectorArithmetic-conforming properties
- Handles multi-dimensional data with
AnimatablePair
Before/After Comparison
Before @Animatable macro
struct HikingRouteShape: Shape {
var startPoint: CGPoint
var endPoint: CGPoint
var elevation: Double
var drawingDirection: Bool
var animatableData: AnimatablePair<AnimatablePair<CGFloat, CGFloat>,
AnimatablePair<Double, AnimatablePair<CGFloat, CGFloat>>> {
get {
AnimatablePair(
AnimatablePair(startPoint.x, startPoint.y),
AnimatablePair(elevation, AnimatablePair(endPoint.x, endPoint.y))
)
}
set {
startPoint = CGPoint(x: newValue.first.first, y: newValue.first.second)
elevation = newValue.second.first
endPoint = CGPoint(x: newValue.second.second.first, y: newValue.second.second.second)
}
}
func path(in rect: CGRect) -> Path {
}
}
After @Animatable macro
@Animatable
struct HikingRouteShape: Shape {
var startPoint: CGPoint
var endPoint: CGPoint
var elevation: Double
@AnimatableIgnored
var drawingDirection: Bool
func path(in rect: CGRect) -> Path {
}
}
Lines of code: 20 → 12 (40% reduction)
@AnimatableIgnored
Use @AnimatableIgnored to exclude properties from animation.
When to use
- Debug values — Flags for development only
- IDs — Identifiers that shouldn't animate
- Timestamps — When the view was created/updated
- Internal state — Non-visual bookkeeping
- Non-VectorArithmetic types — Colors, strings, booleans
Example
@MainActor
@Animatable
struct ProgressView: View {
var progress: Double
var totalItems: Int
