Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, zoom transitions, UIKit/AppKit animation bridging, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26
Provides comprehensive SwiftUI animation guidance including VectorArithmetic, @Animatable macro, zoom transitions, and animation bridging.
npx claudepluginhub charleswiltgen/axiomThis skill inherits all available tools. When active, it can use any tool Claude has access to.
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.
Animation is the process of generating intermediate values between a start and end state.
.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
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.
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)
Animatable attributes conceptually have two values:
Example
.scaleEffect(selected ? 1.5 : 1.0)
When selected becomes true:
1.51.0 → 1.1 → 1.2 → 1.3 → 1.4 → 1.5 over timeThe 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.
Many SwiftUI modifiers conform to Animatable:
.scaleEffect() — Animates scale transform.rotationEffect() — Animates rotation.offset() — Animates position offset.opacity() — Animates transparency.blur() — Animates blur radius.shadow() — Animates shadow propertiesCircle, Rectangle, RoundedRectangleCapsule, Ellipse, PathShape implementationsWhen 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.
struct AnimatableNumberView: View, Animatable {
var number: Double
var animatableData: Double {
get { number }
set { number = newValue }
}
var body: some View {
Text("\(Int(number))")
.font(.largeTitle)
}
}
// Usage
AnimatableNumberView(number: value)
.animation(.spring, value: value)
How it works
number changes from 0 to 100body for every frame of the animationnumber value: 0 → 5 → 15 → 30 → 55 → 80 → 100Custom 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).
The @Animatable macro eliminates the boilerplate of manually conforming to the Animatable protocol.
Before iOS 26, you had to:
AnimatableanimatableData getter and setterAnimatablePair for multiple propertiesiOS 26+, you just add @Animatable:
@MainActor
@Animatable
struct MyView: View {
var scale: CGFloat
var opacity: Double
var body: some View {
// ...
}
}
The macro automatically:
Animatable conformanceanimatableData from VectorArithmetic-conforming propertiesAnimatablePairstruct HikingRouteShape: Shape {
var startPoint: CGPoint
var endPoint: CGPoint
var elevation: Double
var drawingDirection: Bool // Don't want to animate this
// Tedious manual animatableData declaration
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 {
// Drawing code
}
}
@Animatable
struct HikingRouteShape: Shape {
var startPoint: CGPoint
var endPoint: CGPoint
var elevation: Double
@AnimatableIgnored
var drawingDirection: Bool // Excluded from animation
func path(in rect: CGRect) -> Path {
// Drawing code
}
}
Lines of code: 20 → 12 (40% reduction)
Use @AnimatableIgnored to exclude properties from animation.
@MainActor
@Animatable
struct ProgressView: View {
var progress: Double // Animated
var totalItems: Int // Animated (if Float, not if Int)
@AnimatableIgnored
var title: String // Not animated
@AnimatableIgnored
var startTime: Date // Not animated
@AnimatableIgnored
var debugEnabled: Bool // Not animated
var body: some View {
VStack {
Text(title)
ProgressBar(value: progress)
if debugEnabled {
Text("Started: \(startTime.formatted())")
}
}
}
}
@Animatable works for any numeric display — stock prices, heart rate, scores, timers, progress bars:
@MainActor
@Animatable
struct AnimatedValueView: View {
var value: Double
var changePercent: Double
@AnimatableIgnored
var label: String
var body: some View {
VStack(alignment: .trailing) {
Text("\(value, format: .number.precision(.fractionLength(2)))")
.font(.title)
Text("\(changePercent > 0 ? "+" : "")\(changePercent, format: .percent)")
.foregroundStyle(changePercent > 0 ? .green : .red)
}
}
}
// Usage
AnimatedValueView(value: currentPrice, changePercent: 0.025, label: "Price")
.animation(.spring(duration: 0.8), value: currentPrice)
Timing curve animations use bezier curves to control the speed of animation over time.
.animation(.linear) // Constant speed
.animation(.easeIn) // Starts slow, ends fast
.animation(.easeOut) // Starts fast, ends slow
.animation(.easeInOut) // Slow start and end, fast middle
let customCurve = UnitCurve(
startControlPoint: CGPoint(x: 0.2, y: 0),
endControlPoint: CGPoint(x: 0.8, y: 1)
)
.animation(.timingCurve(customCurve, duration: 0.5))
All timing curve animations accept an optional duration:
.animation(.easeInOut(duration: 0.3))
.animation(.linear(duration: 1.0))
Default: 0.35 seconds
Spring animations use physics simulation to create natural, organic motion.
.animation(.smooth) // No bounce (default since iOS 17)
.animation(.snappy) // Small amount of bounce
.animation(.bouncy) // Larger amount of bounce
.animation(.spring(duration: 0.6, bounce: 0.3))
Parameters
duration — Perceived animation durationbounce — Amount of bounce (0 = no bounce, 1 = very bouncy)Much more intuitive than traditional spring parameters (mass, stiffness, damping).
Modify base animations to create complex effects.
.animation(.spring.delay(0.5))
Waits 0.5 seconds before starting the animation.
.animation(.easeInOut.repeatCount(3, autoreverses: true))
.animation(.linear.repeatForever(autoreverses: false))
Repeats the animation multiple times or infinitely.
.animation(.spring.speed(2.0)) // 2x faster
.animation(.spring.speed(0.5)) // 2x slower
Multiplies the animation speed.
Before iOS 17
withAnimation {
// Used timing curve by default
}
iOS 17+
withAnimation {
// Uses .smooth spring by default
}
Why the change: Spring animations feel more natural and preserve velocity when interrupted.
Recommendation: Embrace springs. They make your UI feel more responsive and polished.
The most common way to trigger an animation.
Button("Scale Up") {
withAnimation(.spring) {
scale = 1.5
}
}
How it works
withAnimation opens a transactionwithAnimation(.spring(duration: 0.6, bounce: 0.4)) {
isExpanded.toggle()
}
withAnimation(nil) {
// Changes happen immediately, no animation
resetState()
}
Apply animations to specific values within a view.
Circle()
.fill(isActive ? .blue : .gray)
.animation(.spring, value: isActive)
How it works: Animation only applies when isActive changes. Other state changes won't trigger this animation.
Circle()
.scaleEffect(scale)
.animation(.bouncy, value: scale)
.opacity(opacity)
.animation(.easeInOut, value: opacity)
Different animations for different properties.
Narrowly scope animations to specific animatable attributes.
struct AvatarView: View {
var selected: Bool
var body: some View {
Image("avatar")
.scaleEffect(selected ? 1.5 : 1.0)
.animation(.spring, value: selected)
// ⚠️ If image also changes when selected changes,
// image transition gets animated too (accidental)
}
}
struct AvatarView: View {
var selected: Bool
var body: some View {
Image("avatar")
.animation(.spring, value: selected) {
$0.scaleEffect(selected ? 1.5 : 1.0)
}
// ✅ Only scaleEffect animates, image transition doesn't
}
}
How it works
Define custom TransactionKey types to propagate context through the transaction system. Use withTransaction to set values and .transaction modifier to read them. This enables applying different animations based on how a state change was triggered (tap vs programmatic).
Implement your own animation algorithms.
protocol CustomAnimation {
// Calculate current value
func animate<V: VectorArithmetic>(
value: V,
time: TimeInterval,
context: inout AnimationContext<V>
) -> V?
// Optional: Should this animation merge with previous?
func shouldMerge<V>(previous: Animation, value: V, time: TimeInterval, context: inout AnimationContext<V>) -> Bool
// Optional: Current velocity
func velocity<V: VectorArithmetic>(
value: V,
time: TimeInterval,
context: AnimationContext<V>
) -> V?
}
struct LinearAnimation: CustomAnimation {
let duration: TimeInterval
func animate<V: VectorArithmetic>(
value: V, // Delta vector: target - current
time: TimeInterval,
context: inout AnimationContext<V>
) -> V? {
if time >= duration { return nil }
return value.scaled(by: time / duration)
}
}
Critical understanding: value is the delta vector (target - current), not the target. Return nil when done. SwiftUI adds the scaled delta to the current value automatically.
What happens when a new animation starts before the previous one finishes?
func shouldMerge(...) -> Bool {
return false // Default implementation
}
Behavior: Both animations run together, results are combined additively.
Example
func shouldMerge(...) -> Bool {
return true // Springs override this
}
Behavior: New animation incorporates state of previous animation, preserving velocity.
Example
Why springs feel more natural: They preserve momentum when interrupted.
Cycles through a sequence of phases, applying different modifiers at each phase. Each phase transition is independently animated.
PhaseAnimator([false, true]) { phase in
Image(systemName: "star.fill")
.scaleEffect(phase ? 1.5 : 1.0)
.opacity(phase ? 1.0 : 0.5)
.rotationEffect(.degrees(phase ? 360 : 0))
} animation: { phase in
phase ? .spring(duration: 0.8, bounce: 0.3) : .easeInOut(duration: 0.4)
}
How it works: Begins at first phase, animates to second, then loops. The animation closure returns the animation used to transition INTO that phase. Phases can be any Equatable type — use an enum for complex multi-step sequences:
enum PulsePhase: CaseIterable { case idle, expand, contract }
PhaseAnimator(PulsePhase.allCases) { phase in
Circle()
.scaleEffect(phase == .expand ? 1.3 : phase == .contract ? 0.9 : 1.0)
}
Trigger: Add a trigger parameter to run the animation only when a value changes (instead of looping continuously).
Provides per-property keyframe tracks for precise, timeline-based animations. More control than PhaseAnimator.
struct AnimationValues {
var scale: Double = 1.0
var rotation: Angle = .zero
var yOffset: Double = 0
}
KeyframeAnimator(initialValue: AnimationValues()) { values in
Image(systemName: "heart.fill")
.scaleEffect(values.scale)
.rotationEffect(values.rotation)
.offset(y: values.yOffset)
} keyframes: { _ in
KeyframeTrack(\.scale) {
SpringKeyframe(1.5, duration: 0.3)
SpringKeyframe(1.0, duration: 0.3)
}
KeyframeTrack(\.rotation) {
LinearKeyframe(.degrees(15), duration: 0.15)
LinearKeyframe(.degrees(-15), duration: 0.3)
LinearKeyframe(.zero, duration: 0.15)
}
KeyframeTrack(\.yOffset) {
CubicKeyframe(-20, duration: 0.3)
CubicKeyframe(0, duration: 0.3)
}
}
Keyframe types: LinearKeyframe (constant velocity), SpringKeyframe (spring physics), CubicKeyframe (bezier curves), MoveKeyframe (instant jump, no interpolation).
vs PhaseAnimator: Use PhaseAnimator for simple state cycling. Use KeyframeAnimator when different properties need independent timing.
Defines how a view animates when inserted/removed from the view hierarchy.
if showDetail {
DetailView()
.transition(.slide) // Slide in/out
.transition(.scale.combined(with: .opacity)) // Combine transitions
.transition(.move(edge: .bottom)) // Move from edge
.transition(.asymmetric( // Different in/out
insertion: .scale.combined(with: .opacity),
removal: .opacity
))
}
Requires animation context — wrap the state change in withAnimation or use .animation() modifier. Without animation, the view appears/disappears instantly.
Smoothly animate a view's frame between two positions in the hierarchy. Commonly used for hero transitions and shared element animations.
@Namespace private var animation
// Source
if !isExpanded {
RoundedRectangle(cornerRadius: 10)
.matchedGeometryEffect(id: "card", in: animation)
.frame(width: 100, height: 100)
}
// Destination
if isExpanded {
RoundedRectangle(cornerRadius: 20)
.matchedGeometryEffect(id: "card", in: animation)
.frame(width: 300, height: 400)
}
Key rules: Same id + same Namespace = matched pair. Only one view with a given ID should be isSource: true (default) at a time. Wrap state change in withAnimation for smooth interpolation.
Animates changes to text and symbol content within a view (iOS 16+).
Text(value, format: .number)
.contentTransition(.numericText(countsDown: value < previous))
Image(systemName: isFavorite ? "heart.fill" : "heart")
.contentTransition(.symbolEffect(.replace))
iOS 18 introduces the zoom transition, where a tapped cell morphs into the incoming view. This transition is continuously interactive—users can grab and drag the view during or after the transition begins.
Key benefit In parts of your app where you transition from a large cell, zoom transitions increase visual continuity by keeping the same UI elements on screen across the transition.
Two steps to adopt zoom transitions:
NavigationLink {
BraceletEditor(bracelet)
.navigationTransition(.zoom(sourceID: bracelet.id, in: namespace))
} label: {
BraceletPreview(bracelet)
}
BraceletPreview(bracelet)
.matchedTransitionSource(id: bracelet.id, in: namespace)
struct BraceletListView: View {
@Namespace private var braceletList
let bracelets: [Bracelet]
var body: some View {
NavigationStack {
ScrollView {
LazyVGrid(columns: [GridItem(.adaptive(minimum: 150))]) {
ForEach(bracelets) { bracelet in
NavigationLink {
BraceletEditor(bracelet: bracelet)
.navigationTransition(
.zoom(sourceID: bracelet.id, in: braceletList)
)
} label: {
BraceletPreview(bracelet: bracelet)
}
.matchedTransitionSource(id: bracelet.id, in: braceletList)
}
}
}
}
}
}
Set preferredTransition = .zoom { context in ... } on the pushed view controller. The closure returns the source view and is called on both zoom in and zoom out — capture a stable identifier (model object), not a view directly.
Zoom transitions also work with fullScreenCover and sheet:
.fullScreenCover(item: $selectedBracelet) { bracelet in
BraceletEditor(bracelet: bracelet)
.navigationTransition(.zoom(sourceID: bracelet.id, in: namespace))
}
.matchedTransitionSource(id: bracelet.id, in: namespace) { source in
source.cornerRadius(8.0).shadow(radius: 4)
}
Push transitions cannot be cancelled — when interrupted, they convert to pop transitions. The view controller always reaches the Appeared state. Don't guard against overlapping transitions; let the system handle them.
iOS 18 enables using SwiftUI Animation types to animate UIKit and AppKit views. This provides access to the full suite of SwiftUI animations, including custom animations.
// Old way
UIView.animate(withDuration: 0.5, delay: 0,
usingSpringWithDamping: 0.7, initialSpringVelocity: 0.5) {
bead.center = endOfBracelet
}
// New way: Use SwiftUI Animation type
UIView.animate(.spring(duration: 0.5)) {
bead.center = endOfBracelet
}
All SwiftUI animations work: .linear, .easeIn/Out, .spring, .smooth, .snappy, .bouncy, .repeatForever(), and custom animations.
Architecture note: Unlike old UIKit APIs, no CAAnimation is generated — presentation values are animated directly.
When wrapping UIKit views in SwiftUI, animations don't automatically bridge:
struct BeadBoxWrapper: UIViewRepresentable {
@Binding var isOpen: Bool
func updateUIView(_ box: BeadBox, context: Context) {
// ❌ Animation on binding doesn't affect UIKit
box.lid.center.y = isOpen ? -100 : 100
}
}
// Usage
BeadBoxWrapper(isOpen: $isOpen)
.animation(.spring, value: isOpen) // No effect on UIKit view
Use context.animate() to bridge SwiftUI animations:
struct BeadBoxWrapper: UIViewRepresentable {
@Binding var isOpen: Bool
func makeUIView(context: Context) -> BeadBox {
BeadBox()
}
func updateUIView(_ box: BeadBox, context: Context) {
// ✅ Bridges animation from Transaction to UIKit
context.animate {
box.lid.center.y = isOpen ? -100 : 100
}
}
}
Transactioncontext.animate() reads the Transaction's animationcontext.animate {
// Changes here
} completion: {
// Called when animation completes
// If not animated, called immediately inline
}
Works whether animated or not — safe to always use this pattern.
A single animation running across SwiftUI Views and UIViews runs perfectly in sync. This enables seamless mixed hierarchies.
SwiftUI animations automatically preserve velocity through animation merging — no manual velocity calculation needed:
// UIKit with SwiftUI animations
func handlePan(_ gesture: UIPanGestureRecognizer) {
switch gesture.state {
case .changed:
UIView.animate(.interactiveSpring) {
bead.center = gesture.location(in: view)
}
case .ended:
UIView.animate(.spring) { // Inherits velocity automatically
bead.center = endOfBracelet
}
default: break
}
}
// Pure SwiftUI equivalent
DragGesture()
.onChanged { value in
withAnimation(.interactiveSpring) { position = value.location }
}
.onEnded { _ in
withAnimation(.spring) { position = targetPosition }
}
Each .interactiveSpring retargets the previous animation, and the final .spring inherits the accumulated velocity for smooth deceleration.
Check in order:
Int can't animate; use Double/Float.animation(.spring, value: x) or withAnimation.animation(.spring, value: progress) not .animation(.spring, value: title)@Animatable (iOS 26+) or manual animatableDataCustom Animatable conformance calls body every frame on main thread. Use built-in effects (.opacity(), .scaleEffect()) when possible — they run off-main-thread. Profile with Instruments for complex cases.
Spring animations merge by default, preserving velocity. Use timing curve animations (.easeInOut) if you don't want merging behavior. See Animation Merging Behavior section above.
WWDC: 2023-10156, 2023-10157, 2023-10158, 2024-10145, 2025-256
Docs: /swiftui/animatable, /swiftui/animation, /swiftui/vectorarithmetic, /swiftui/transaction, /swiftui/view/navigationtransition(:), /swiftui/view/matchedtransitionsource(id:in:configuration:), /uikit/uiview/animate(:changes:completion:)
Skills: axiom-swiftui-26-ref, axiom-swiftui-nav-ref, axiom-swiftui-performance, axiom-swiftui-debugging, axiom-sf-symbols-ref
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.